为 Python 代码添加文档

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

按照以下说明来记录、生成和发布新的 Python docstring

1. 将 docstring 直接添加到目标方法名称下方。至少请添加以下内容的描述：

   • 方法的函数行为

   • 参数，由 Args 部分表示

   • 返回值，由 Returns 部分表示

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

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

   下面是一个 Python docstring 示例

   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 文档端，向相应的 .rst 文件添加一个 autofunction 指令。如果对应的 Python 源文件没有 .rst 文件，请创建一个与 Python 源文件同名的新文件。使用上述示例：

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

3. 确保 .rst 文件包含在 index.rst 的 toctree 中（例如 FBGEMM_GPU Python API）。

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

---

上面的 Python docstring 示例生成以下 HTML 输出

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

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

代码示例

// 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;
}

这里是一个逐字文本图示例

.------+---------------------------------.-----------------------------
|            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) – param 的描述。

返回值：

方法返回值的描述。

抛出：

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

• ValueError – 如果 param 等于 3.14。

示例

以下是使用此函数的方法

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

注意

有关 reStructuredText docstring 的更多信息，请参阅 此处 和 此处。

---

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

许多 FBGEMM_GPU Python API 方法在构建过程中通过 PyTorch 自动生成，需要事后附加 docstring。按照以下说明为自动生成的 Python 方法添加文档

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

2. 在 Python 文件中，使用 fbgemm_gpu.docs.common 中提供的辅助方法，按方法名称将 docstring 附加到目标自动生成的方法。下面是一个代码库中的示例：

   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 代码添加文档 中的剩余步骤，在文档中渲染 docstring。