为 Python 代码添加文档

Python 的文档通过文档字符串提供，并使用 Sphinx 生成。请参考 Google 风格的 Python 文档字符串 指南，了解文档字符串格式示例。

按照这些说明来记录、生成和发布新的 Python 文档字符串

1. 将文档字符串直接添加到目标方法名称下。至少，请添加以下描述：

   • 方法的功能行为

   • 参数，由 Args 部分表示

   • 返回值，由 Returns 部分表示

   • 可能抛出的异常（如果适用），由 Raises 部分表示

   其他部分，如 Todo、Note 和 Example，应根据需要添加。

   这是一个 Python 文档字符串示例

   def example_method(alignment: c_size_t, param: float) -> int:
       """
       This class is an example of how you can write docstrings.
       You can add multiple lines of those descriptions. Make sure to include
       useful information about your method.
   
       **Code Example:**
   
       .. code-block:: cpp
   
           // Here is a C++ code block
           std::vector<int32_t> foo(const std::vector<int32_t> &lst) {
               std::vector<int32_t> ret;
               for (const auto x : lst) {
                   ret.emplace_back(x * 2);
               }
               return ret;
           }
   
       And here is a verbatim-text diagram example:
   
       .. code-block:: text
   
           .------+---------------------------------.-----------------------------
           |            Block A (first)             |       Block B (second)
           +------+------+--------------------------+------+------+---------------
           | Next | Prev |   usable space           | Next | Prev | usable space..
           +------+------+--------------------------+------+--+---+---------------
           ^  |                                     ^         |
           |  '-------------------------------------'         |
           |                                                  |
           '----------- Block B's prev points to Block A -----'
   
       Todo:
           * This is a TODO item.
           * And a second TODO item.
   
       Args:
           alignment (c_size_t): Description of the `alignment` value.
           param (float): Description of `param1`.
   
       Returns:
           Description of the method's return value.
   
       Raises:
           AttributeError: If there is an error with the attributes.
           ValueError: If `param` is equal to 3.14.
   
       Example:
           This is how you can use this function
   
           >>> print("Code blocks are supported")
   
       Note:
           For more info on reStructuredText docstrings, see
           `here <https://sphinx-doc.cn/en/master/usage/restructuredtext/basics.html>`__
           and
           `here <https://peps.pythonlang.cn/pep-0287/>`__.
       """
       return 42
   
   
   

2. 在 Sphinx 文档方面，将 autofunction 指令添加到相应的 .rst 文件。如果相应的 Python 源文件不存在 .rst 文件，则创建一个与 Python 源文件同名的新文件。使用上面的示例

   .. autofunction:: fbgemm_gpu.docs.examples.example_method
   

3. 确保 .rst 文件包含在 index.rst 的 toctree 中（例如 fbgemm-gpu.toc.api.python）。

4. 通过在本地使用 构建文档 构建文档或提交 PR 以进行 Netlify 预览来验证更改。

---

上面的 Python 文档字符串示例生成以下 HTML 输出

fbgemm_gpu.docs.examples.example_method(alignment: c_ulong, param: float) → int

此类是如何编写文档字符串的示例。您可以添加多行描述。请确保包含有关您方法的有用信息。

代码示例

// Here is a C++ code block
std::vector<int32_t> foo(const std::vector<int32_t> &lst) {
    std::vector<int32_t> ret;
    for (const auto x : lst) {
        ret.emplace_back(x * 2);
    }
    return ret;
}

这是一个 verbatim-text 图表示例

.------+---------------------------------.-----------------------------
|            Block A (first)             |       Block B (second)
+------+------+--------------------------+------+------+---------------
| Next | Prev |   usable space           | Next | Prev | usable space..
+------+------+--------------------------+------+--+---+---------------
^  |                                     ^         |
|  '-------------------------------------'         |
|                                                  |
'----------- Block B's prev points to Block A -----'

待办事项

• 这是一个待办事项。

• 以及第二个待办事项。

参数:

• alignment (c_size_t) – alignment 值的描述。

• param (float) – param1 的描述。

返回值:

方法返回值的描述。

抛出:

• AttributeError – 如果属性出现错误。

• ValueError – 如果 param 等于 3.14。

示例

这是您如何使用此函数的方法

>>> print("Code blocks are supported")

注意

有关 reStructuredText 文档字符串的更多信息，请参阅此处和此处。

---

为自动生成的 Python 代码添加文档

许多 FBGEMM_GPU Python API 方法是在构建过程中通过 PyTorch 自动生成的，并且需要在事后附加文档字符串。按照这些说明来记录自动生成的 Python 方法

1. 如果需要，在 repo 中的 fbgemm_gpu/fbgemm_gpu/docs 下创建一个 Python 文件。

2. 在 Python 文件中，使用 fbgemm_gpu.docs.common 中提供的帮助方法，通过方法名称将文档字符串附加到目标自动生成的方法。这是一个来自代码库的示例

   import torch
   
   from .common import add_docs
   
   
   add_docs(
       torch.ops.fbgemm.jagged_2d_to_dense,
       """
   jagged_2d_to_dense(values, x_offsets, max_sequence_length) -> Tensor
   
   Converts a jagged tensor, with a 2D values array into a dense tensor, padding with zeros.
   
   Args:
       values (Tensor): 2D tensor containing the values of the jagged tensor.
   
       x_offsets (Tensor): 1D tensor containing the starting point of each jagged row in the values tensor.
   
       max_sequence_length (int): Maximum length of any row in the jagged dimension.
   
   Returns:
       Tensor: The padded dense tensor
   
   Example:
       >>> values = torch.tensor([[1,1],[2,2],[3,3],[4,4]])
       >>> x_offsets = torch.tensor([0, 1, 3])
       >>> torch.ops.fbgemm.jagged_2d_to_dense(values, x_offsets, 3)
       tensor([[[1, 1],
                [0, 0],
                [0, 0]],
               [[2, 2],
                [3, 3],
                [0, 0]]])
   
   """,
   )
   

3. 如果尚未存在，请将 Python 文件附加到 fbgemm_gpu/fbgemm_gpu/docs/__init__.py 中的导入列表。这将强制在 fbgemm_gpu 模块加载时加载临时文档。例如

   from . import the_new_doc_module
   

4. 按照 为 Python 代码添加文档 中的其余步骤在文档中渲染文档字符串。