docstring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PyTorch Docstring Writing Guide

PyTorch文档字符串编写指南

This skill describes how to write docstrings for functions and methods in the PyTorch project, following the conventions in

torch/_tensor_docs.py

and

torch/nn/functional.py

本指南介绍如何遵循

torch/_tensor_docs.py

和

torch/nn/functional.py

中的规范，为PyTorch项目中的函数和方法编写文档字符串。

General Principles

通用原则

Use raw strings (
```
r"""..."""
```
) for all docstrings to avoid issues with LaTeX/math backslashes
Follow Sphinx/reStructuredText (reST) format for documentation
Be concise but complete - include all essential information
Always include examples when possible
Use cross-references to related functions/classes

所有文档字符串均使用原始字符串（
```
r"""..."""
```
），以避免LaTeX/数学反斜杠相关问题
文档采用Sphinx/reStructuredText（reST）格式
内容需简洁但完整，包含所有必要信息
尽可能添加示例
使用交叉引用关联相关函数/类

Docstring Structure

文档字符串结构

1. Function Signature (First Line)

1. 函数签名（第一行）

Start with the function signature showing all parameters:

python

r"""function_name(param1, param2, *, kwarg1=default1, kwarg2=default2) -> ReturnType

Notes:

Include the function name
Show positional and keyword-only arguments (use
```
*
```
separator)
Include default values
Show return type annotation
This line should NOT end with a period

以包含所有参数的函数签名开头：

python

r"""function_name(param1, param2, *, kwarg1=default1, kwarg2=default2) -> ReturnType

注意事项：

包含函数名称
显示位置参数和仅限关键字参数（使用
```
*
```
分隔）
包含默认值
显示返回类型注解
此行末尾不使用句号

2. Brief Description

2. 简要描述

Provide a one-line description of what the function does:

python

r"""conv2d(input, weight, bias=None, stride=1, padding=0, dilation=1, groups=1) -> Tensor

Applies a 2D convolution over an input image composed of several input
planes.

用一行文字说明函数的功能：

python

r"""conv2d(input, weight, bias=None, stride=1, padding=0, dilation=1, groups=1) -> Tensor

对由多个输入平面组成的输入图像应用二维卷积。

3. Mathematical Formulas (if applicable)

3. 数学公式（如适用）

Use Sphinx math directives for mathematical expressions:

python

.. math::
    \text{Softmax}(x_{i}) = \frac{\exp(x_i)}{\sum_j \exp(x_j)}

Or inline math:

:math:\

x^2``

使用Sphinx数学指令编写数学表达式：

python

.. math::
    \text{Softmax}(x_{i}) = \frac{\exp(x_i)}{\sum_j \exp(x_j)}

或使用行内数学表达式：

:math:\

x^2``

4. Cross-References

4. 交叉引用

Link to related classes and functions using Sphinx roles:

```
:class:\
```
~torch.nn.ModuleName`` - Link to a class
```
:func:\
```
torch.function_name`` - Link to a function
```
:meth:\
```
~Tensor.method_name`` - Link to a method
```
:attr:\
```
attribute_name`` - Reference an attribute
The
```
~
```
prefix shows only the last component (e.g.,
```
Conv2d
```
instead of
```
torch.nn.Conv2d
```
)

Example:

python

See :class:`~torch.nn.Conv2d` for details and output shape.

使用Sphinx角色链接到相关类和函数：

```
:class:\
```
~torch.nn.ModuleName`` - 链接到类
```
:func:\
```
torch.function_name`` - 链接到函数
```
:meth:\
```
~Tensor.method_name`` - 链接到方法
```
:attr:\
```
attribute_name`` - 引用属性
```
~
```
前缀仅显示最后一部分（例如，显示
```
Conv2d
```
而非
```
torch.nn.Conv2d
```
）

示例：

python

详情和输出形状请参见:class:`~torch.nn.Conv2d`。

5. Notes and Warnings

5. 注意和警告

Use admonitions for important information:

python

.. note::
    This function doesn't work directly with NLLLoss,
    which expects the Log to be computed between the Softmax and itself.
    Use log_softmax instead (it's faster and has better numerical properties).

.. warning::
    :func:`new_tensor` always copies :attr:`data`. If you have a Tensor
    ``data`` and want to avoid a copy, use :func:`torch.Tensor.requires_grad_`
    or :func:`torch.Tensor.detach`.

使用警告框展示重要信息：

python

.. note::
    该函数无法直接与NLLLoss配合使用，NLLLoss要求在Softmax和自身之间计算Log。
    请改用log_softmax（速度更快，数值特性更好）。

.. warning::
    :func:`new_tensor`始终会复制:attr:`data`。如果您已有一个Tensor
    ``data``且想避免复制，请使用:func:`torch.Tensor.requires_grad_`
    或:func:`torch.Tensor.detach`。

6. Args Section

6. 参数部分

Document all parameters with type annotations and descriptions:

python

Args:
    input (Tensor): input tensor of shape :math:`(\text{minibatch} , \text{in\_channels} , iH , iW)`
    weight (Tensor): filters of shape :math:`(\text{out\_channels} , kH , kW)`
    bias (Tensor, optional): optional bias tensor of shape :math:`(\text{out\_channels})`. Default: ``None``
    stride (int or tuple): the stride of the convolving kernel. Can be a single number or a
      tuple `(sH, sW)`. Default: 1

Formatting rules:

Parameter name in lowercase
Type in parentheses:
```
(Type)
```
,
```
(Type, optional)
```
for optional parameters
Description follows the type
For optional parameters, include "Default:
```
value
```
" at the end
Use double backticks for inline code:
```
``None``
```
Indent continuation lines by 2 spaces

为所有参数添加类型注解和描述：

python

Args:
    input (Tensor): 形状为:math:`(\text{minibatch} , \text{in\_channels} , iH , iW)`的输入张量
    weight (Tensor): 形状为:math:`(\text{out\_channels} , kH , kW)`的滤波器
    bias (Tensor, optional): 形状为:math:`(\text{out\_channels})`的可选偏置张量。默认值：``None``
    stride (int or tuple): 卷积核的步长。可以是单个数字或
      元组`(sH, sW)`。默认值：1

格式规则：

参数名称为小写
类型放在括号中：
```
(Type)
```
，可选参数使用
```
(Type, optional)
```
描述紧跟类型之后
可选参数末尾需包含“Default:
```
value
```
”
行内代码使用双反引号：
```
``None``
```
描述换行时缩进2个空格

7. Keyword Args Section (if applicable)

7. 关键字参数部分（如适用）

Sometimes keyword arguments are documented separately:

python

Keyword args:
    dtype (:class:`torch.dtype`, optional): the desired type of returned tensor.
        Default: if None, same :class:`torch.dtype` as this tensor.
    device (:class:`torch.device`, optional): the desired device of returned tensor.
        Default: if None, same :class:`torch.device` as this tensor.
    requires_grad (bool, optional): If autograd should record operations on the
        returned tensor. Default: ``False``.

有时关键字参数会单独记录：

python

Keyword args:
    dtype (:class:`torch.dtype`, optional): 返回张量的期望类型。
        默认值：如果为None，则与当前张量的:class:`torch.dtype`相同。
    device (:class:`torch.device`, optional): 返回张量的期望设备。
        默认值：如果为None，则与当前张量的:class:`torch.device`相同。
    requires_grad (bool, optional): 是否让autograd记录返回张量上的操作。默认值：``False``。

8. Returns Section (if needed)

8. 返回值部分（如需要）

Document the return value:

python

Returns:
    Tensor: Sampled tensor of same shape as `logits` from the Gumbel-Softmax distribution.
        If ``hard=True``, the returned samples will be one-hot, otherwise they will
        be probability distributions that sum to 1 across `dim`.

Or simply include it in the function signature line if obvious from context.

记录返回值：

python

Returns:
    Tensor: 从Gumbel-Softmax分布采样得到的与`logits`形状相同的张量。
        如果``hard=True``，返回的样本将是独热编码形式，否则将是
        在`dim`维度上求和为1的概率分布。

如果上下文已明确说明，也可直接在函数签名行中体现。

9. Examples Section

9. 示例部分

Always include examples when possible:

python

Examples::

    >>> inputs = torch.randn(33, 16, 30)
    >>> filters = torch.randn(20, 16, 5)
    >>> F.conv1d(inputs, filters)

    >>> # With square kernels and equal stride
    >>> filters = torch.randn(8, 4, 3, 3)
    >>> inputs = torch.randn(1, 4, 5, 5)
    >>> F.conv2d(inputs, filters, padding=1)

Formatting rules:

Use
```
Examples::
```
with double colon
Use
```
>>>
```
prompt for Python code
Include comments with
```
#
```
when helpful
Show actual output when it helps understanding (indent without
```
>>>
```
)

尽可能添加示例：

python

Examples::

    >>> inputs = torch.randn(33, 16, 30)
    >>> filters = torch.randn(20, 16, 5)
    >>> F.conv1d(inputs, filters)

    >>> # 使用方形核和相等步长
    >>> filters = torch.randn(8, 4, 3, 3)
    >>> inputs = torch.randn(1, 4, 5, 5)
    >>> F.conv2d(inputs, filters, padding=1)

格式规则：

使用
```
Examples::
```
（双冒号）
Python代码使用
```
>>>
```
提示符
必要时使用
```
#
```
添加注释
有助于理解时可展示实际输出（不使用
```
>>>
```
，直接缩进）

10. External References

10. 外部引用

Link to papers or external documentation:

python

.. _Link Name:
    https://arxiv.org/abs/1611.00712

Reference them in text:

See `Link Name`_

链接到论文或外部文档：

python

.. _Link Name:
    https://arxiv.org/abs/1611.00712

在正文中引用：

请参见`Link Name`_

Method Types

方法类型

Native Python Functions

原生Python函数

For regular Python functions, use a standard docstring:

python

def relu(input: Tensor, inplace: bool = False) -> Tensor:
    r"""relu(input, inplace=False) -> Tensor

    Applies the rectified linear unit function element-wise. See
    :class:`~torch.nn.ReLU` for more details.
    """
    # implementation

常规Python函数使用标准文档字符串：

python

def relu(input: Tensor, inplace: bool = False) -> Tensor:
    r"""relu(input, inplace=False) -> Tensor

    逐元素应用整流线性单元函数。详情请参见
    :class:`~torch.nn.ReLU`。
    """
    # 实现代码

C-Bound Functions (using add_docstr)

绑定C的函数（使用add_docstr）

For C-bound functions, use

_add_docstr

python

conv1d = _add_docstr(
    torch.conv1d,
    r"""
conv1d(input, weight, bias=None, stride=1, padding=0, dilation=1, groups=1) -> Tensor

Applies a 1D convolution over an input signal composed of several input
planes.

See :class:`~torch.nn.Conv1d` for details and output shape.

Args:
    input: input tensor of shape :math:`(\text{minibatch} , \text{in\_channels} , iW)`
    weight: filters of shape :math:`(\text{out\_channels} , kW)`
    ...
""",
)

对于绑定C的函数，使用

_add_docstr

：

python

conv1d = _add_docstr(
    torch.conv1d,
    r"""
conv1d(input, weight, bias=None, stride=1, padding=0, dilation=1, groups=1) -> Tensor

对由多个输入平面组成的输入信号应用一维卷积。

详情和输出形状请参见:class:`~torch.nn.Conv1d`。

Args:
    input: 形状为:math:`(\text{minibatch} , \text{in\_channels} , iW)`的输入张量
    weight: 形状为:math:`(\text{out\_channels} , kW)`的滤波器
    ...
""",
)

In-Place Variants

原地操作变体

For in-place operations (ending with

), reference the original:

python

add_docstr_all(
    "abs_",
    r"""
abs_() -> Tensor

In-place version of :meth:`~Tensor.abs`
""",
)

对于以

结尾的原地操作，引用原函数：

python

add_docstr_all(
    "abs_",
    r"""
abs_() -> Tensor

:meth:`~Tensor.abs`的原地版本
""",
)

Alias Functions

别名函数

For aliases, simply reference the original:

python

add_docstr_all(
    "absolute",
    r"""
absolute() -> Tensor

Alias for :func:`abs`
""",
)

对于别名函数，直接引用原函数：

python

add_docstr_all(
    "absolute",
    r"""
absolute() -> Tensor

:func:`abs`的别名
""",
)

Common Patterns

常见模式

Shape Documentation

形状文档

Use LaTeX math notation for tensor shapes:

python

:math:`(\text{minibatch} , \text{in\_channels} , iH , iW)`

使用LaTeX数学符号表示张量形状：

python

:math:`(\text{minibatch} , \text{in\_channels} , iH , iW)`

Reusable Argument Definitions

可复用参数定义

For commonly used arguments, define them once and reuse:

python

common_args = parse_kwargs(
    """
    dtype (:class:`torch.dtype`, optional): the desired type of returned tensor.
        Default: if None, same as this tensor.
"""
)

对于常用参数，定义一次后复用：

python

common_args = parse_kwargs(
    """
    dtype (:class:`torch.dtype`, optional): 返回张量的期望类型。
        默认值：如果为None，则与当前张量相同。
"""
)

Then use with .format():

然后使用.format()调用：

r""" ...

Keyword args: {dtype} {device} """.format(**common_args)

undefined

r""" ...

Keyword args: {dtype} {device} """.format(**common_args)

undefined

Template Insertion

模板插入

Insert reproducibility notes or other common text:

python

r"""
{tf32_note}

{cudnn_reproducibility_note}
""".format(**reproducibility_notes, **tf32_notes)

插入可复现性说明或其他通用文本：

python

r"""
{tf32_note}

{cudnn_reproducibility_note}
""".format(**reproducibility_notes, **tf32_notes)

Complete Example

完整示例

Here's a complete example showing all elements:

python

def gumbel_softmax(
    logits: Tensor,
    tau: float = 1,
    hard: bool = False,
    eps: float = 1e-10,
    dim: int = -1,
) -> Tensor:
    r"""
    Sample from the Gumbel-Softmax distribution and optionally discretize.

    Args:
        logits (Tensor): `[..., num_features]` unnormalized log probabilities
        tau (float): non-negative scalar temperature
        hard (bool): if ``True``, the returned samples will be discretized as one-hot vectors,
              but will be differentiated as if it is the soft sample in autograd. Default: ``False``
        dim (int): A dimension along which softmax will be computed. Default: -1

    Returns:
        Tensor: Sampled tensor of same shape as `logits` from the Gumbel-Softmax distribution.
            If ``hard=True``, the returned samples will be one-hot, otherwise they will
            be probability distributions that sum to 1 across `dim`.

    .. note::
        This function is here for legacy reasons, may be removed from nn.Functional in the future.

    Examples::
        >>> logits = torch.randn(20, 32)
        >>> # Sample soft categorical using reparametrization trick:
        >>> F.gumbel_softmax(logits, tau=1, hard=False)
        >>> # Sample hard categorical using "Straight-through" trick:
        >>> F.gumbel_softmax(logits, tau=1, hard=True)

    .. _Link 1:
        https://arxiv.org/abs/1611.00712
    """
    # implementation

以下是包含所有元素的完整示例：

python

def gumbel_softmax(
    logits: Tensor,
    tau: float = 1,
    hard: bool = False,
    eps: float = 1e-10,
    dim: int = -1,
) -> Tensor:
    r"""
    从Gumbel-Softmax分布中采样并可选地进行离散化。

    Args:
        logits (Tensor): `[..., num_features]`形状的未归一化对数概率
        tau (float): 非负标量温度
        hard (bool): 如果为``True``，返回的样本将被离散化为独热向量，
              但在自动微分中会被视为软样本。默认值：``False``
        dim (int): 计算softmax的维度。默认值：-1

    Returns:
        Tensor: 与`logits`形状相同的Gumbel-Softmax分布采样张量。
            如果``hard=True``，返回的样本为独热编码形式，否则为
            在`dim`维度上求和为1的概率分布。

    .. note::
        该函数仅为兼容保留，未来可能会从nn.Functional中移除。

    Examples::
        >>> logits = torch.randn(20, 32)
        >>> # 使用重参数化技巧采样软分类变量：
        >>> F.gumbel_softmax(logits, tau=1, hard=False)
        >>> # 使用"直通"技巧采样硬分类变量：
        >>> F.gumbel_softmax(logits, tau=1, hard=True)

    .. _Link 1:
        https://arxiv.org/abs/1611.00712
    """
    # 实现代码

Quick Checklist

快速检查清单

When writing a PyTorch docstring, ensure:

Use raw string (
```
r"""
```
)
Include function signature on first line
Provide brief description
Document all parameters in Args section with types
Include default values for optional parameters
Use Sphinx cross-references (
```
:func:
```
,
```
:class:
```
,
```
:meth:
```
)
Add mathematical formulas if applicable
Include at least one example in Examples section
Add warnings/notes for important caveats
Link to related module class with
```
:class:
```
Use proper math notation for tensor shapes
Follow consistent formatting and indentation

编写PyTorch文档字符串时，请确保：

使用原始字符串（
```
r"""
```
）
第一行包含函数签名
提供简要描述
在参数部分记录所有参数及其类型
包含可选参数的默认值
使用Sphinx交叉引用（
```
:func:
```
,
```
:class:
```
,
```
:meth:
```
）
适用时添加数学公式
在示例部分至少添加一个示例
为重要注意事项添加警告/说明
使用
```
:class:
```
链接到相关模块类
使用正确的数学符号表示张量形状
遵循一致的格式和缩进

Common Sphinx Roles Reference

常用Sphinx角色参考

```
:class:\
```
~torch.nn.Module`` - Class reference
```
:func:\
```
torch.function`` - Function reference
```
:meth:\
```
~Tensor.method`` - Method reference
```
:attr:\
```
attribute`` - Attribute reference
```
:math:\
```
equation`` - Inline math
```
:ref:\
```
label`` - Internal reference
```
``code``
```
- Inline code (use double backticks)

```
:class:\
```
~torch.nn.Module`` - 类引用
```
:func:\
```
torch.function`` - 函数引用
```
:meth:\
```
~Tensor.method`` - 方法引用
```
:attr:\
```
attribute`` - 属性引用
```
:math:\
```
equation`` - 行内数学表达式
```
:ref:\
```
label`` - 内部引用
```
``code``
```
- 行内代码（使用双反引号）

Additional Notes

额外说明

Indentation: Use 4 spaces for code, 2 spaces for continuation of parameter descriptions
Line length: Try to keep lines under 100 characters when possible
Periods: End sentences with periods, but not the signature line
Backticks: Use double backticks for code:
```
``True`` ``None`` ``False``
```
Types: Common types are
```
Tensor
```
,
```
int
```
,
```
float
```
,
```
bool
```
,
```
str
```
,
```
tuple
```
,
```
list
```
, etc.

缩进：代码使用4个空格，参数描述换行使用2个空格
行长度：尽可能将行长度控制在100字符以内
句号：句子末尾使用句号，但签名行不使用
反引号：代码使用双反引号：
```
``True`` ``None`` ``False``
```
类型：常见类型包括
```
Tensor
```
,
```
int
```
,
```
float
```
,
```
bool
```
,
```
str
```
,
```
tuple
```
,
```
list
```
等。