为 Python 代码添加文档¶
Python 的文档通过文档字符串提供,并使用 Sphinx 生成。请参考 Google 风格的 Python 文档字符串 指南,了解文档字符串格式示例。
按照这些说明来记录、生成和发布新的 Python 文档字符串
将文档字符串直接添加到目标方法名称下。至少,请添加以下描述:
方法的功能行为
参数,由
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
在 Sphinx 文档方面,将
autofunction
指令添加到相应的.rst
文件。如果相应的 Python 源文件不存在.rst
文件,则创建一个与 Python 源文件同名的新文件。使用上面的示例.. autofunction:: fbgemm_gpu.docs.examples.example_method
确保
.rst
文件包含在index.rst
的toctree
中(例如 fbgemm-gpu.toc.api.python)。通过在本地使用 构建文档 构建文档或提交 PR 以进行 Netlify 预览来验证更改。
上面的 Python 文档字符串示例生成以下 HTML 输出
- fbgemm_gpu.docs.examples.example_method(alignment: c_ulong, param: float) int [source]¶
此类是如何编写文档字符串的示例。您可以添加多行描述。请确保包含有关您方法的有用信息。
代码示例
// 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")
为自动生成的 Python 代码添加文档¶
许多 FBGEMM_GPU Python API 方法是在构建过程中通过 PyTorch 自动生成的,并且需要在事后附加文档字符串。按照这些说明来记录自动生成的 Python 方法
如果需要,在 repo 中的
fbgemm_gpu/fbgemm_gpu/docs
下创建一个 Python 文件。在 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]]]) """, )
如果尚未存在,请将 Python 文件附加到
fbgemm_gpu/fbgemm_gpu/docs/__init__.py
中的导入列表。这将强制在fbgemm_gpu
模块加载时加载临时文档。例如from . import the_new_doc_module
按照 为 Python 代码添加文档 中的其余步骤在文档中渲染文档字符串。