为 Python 代码添加文档¶

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

请按照以下说明为新的 Python docstring 添加文档、生成并发布。

将 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

在 Sphinx 文档方面，将一个 autofunction 指令添加到相应的 .rst 文件中。如果不存在与 Python 源文件对应的 .rst 文件，则创建一个新文件，其名称与 Python 源文件相同。使用上面的示例：
```
.. autofunction:: fbgemm_gpu.docs.examples.example_method
```
确保 .rst 文件已包含在 index.rst 的 toctree 中（例如 FBGEMM_GPU Python API）。
通过在本地使用构建文档来构建文档，或提交 PR 以获得 Netlify 预览，来验证更改。

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

fbgemm_gpu.docs.examples.example_method(alignment: c_ulong, param: float) → int[源代码]¶

这个类是如何编写 docstrings 的一个例子。您可以添加多行这样的描述。请确保包含有关您的方法的有用信息。

代码示例

// 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 -----'

待办事项

这是一项 TODO 事项。
以及第二项 TODO 事项。

参数:

alignment (c_size_t) – alignment 值的描述。
param (float) – param1 的描述。

返回:

方法返回值的描述。

抛出:

AttributeError – 如果属性存在错误。
ValueError – 如果 param 等于 3.14。

示例

这是如何使用此函数

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

注意

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

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

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

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

在 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]]])

""",
)

如果尚不存在，请将 Python 文件添加到 fbgemm_gpu/fbgemm_gpu/docs/__init__.py 的导入列表中。这将强制在加载 fbgemm_gpu 模块时加载临时文档。例如：
```
from . import the_new_doc_module
```
请按照为 Python 代码添加文档中的其余步骤操作，以在文档中呈现 docstring。

为 Python 代码添加文档¶

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

文档

教程

资源