向 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 文档方面，在相应的 .rst 文件中添加一个 autofunction 指令。如果相应 Python 源文件的 .rst 文件不存在，则创建一个与 Python 源文件同名的文件。使用上面的示例

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

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

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

---

上面的 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;
}

以下是一个逐字文本图示例

.------+---------------------------------.-----------------------------
|            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. 如果需要，请在存储库中的 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 代码添加文档 中的剩余步骤操作，以在文档中呈现文档字符串。