npx skills add https://github.com/pytorch/pytorch --skill docstring本技能描述了如何为 PyTorch 项目中的函数和方法编写文档字符串,遵循 torch/_tensor_docs.py 和 torch/nn/functional.py 中的约定。
r"""..."""),以避免 LaTeX/数学反斜杠问题以显示所有参数的函数签名开始:
r"""function_name(param1, param2, *, kwarg1=default1, kwarg2=default2) -> ReturnType
注意事项:
* 分隔符)广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
提供函数功能的一行描述:
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.
对数学表达式使用 Sphinx 数学指令:
.. math::
\text{Softmax}(x_{i}) = \frac{\exp(x_i)}{\sum_j \exp(x_j)}
或行内数学公式::math:\x^2``
使用 Sphinx 角色链接到相关类和函数:
:class:\~torch.nn.ModuleName`` - 链接到类:func:\torch.function_name`` - 链接到函数:meth:\~Tensor.method_name`` - 链接到方法:attr:\attribute_name`` - 引用属性~ 前缀仅显示最后部分(例如,Conv2d 而不是 torch.nn.Conv2d)示例:
See :class:`~torch.nn.Conv2d` for details and output shape.
使用 admonitions 表示重要信息:
.. 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`.
使用类型注解和描述记录所有参数:
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
格式化规则:
(Type),可选参数用 (Type, optional)value"None有时关键字参数会单独记录:
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``.
记录返回值:
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`.
或者如果从上下文中显而易见,只需将其包含在函数签名行中。
尽可能包含示例:
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)
格式化规则:
Examples:: 和双冒号>>> 提示符# 包含注释>>>)链接到论文或外部文档:
.. _Link Name:
https://arxiv.org/abs/1611.00712
在文本中引用它们:See Link Name_
对于常规 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
对于 C 绑定函数,使用 _add_docstr:
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)`
...
""",
)
对于原地操作(以 _ 结尾),引用原始函数:
add_docstr_all(
"abs_",
r"""
abs_() -> Tensor
In-place version of :meth:`~Tensor.abs`
""",
)
对于别名,只需引用原始函数:
add_docstr_all(
"absolute",
r"""
absolute() -> Tensor
Alias for :func:`abs`
""",
)
对张量形状使用 LaTeX 数学符号:
:math:`(\text{minibatch} , \text{in\_channels} , iH , iW)`
对于常用参数,定义一次并重复使用:
common_args = parse_kwargs(
"""
dtype (:class:`torch.dtype`, optional): the desired type of returned tensor.
Default: if None, same as this tensor.
"""
)
# Then use with .format():
r"""
...
Keyword args:
{dtype}
{device}
""".format(**common_args)
插入可重现性说明或其他常见文本:
r"""
{tf32_note}
{cudnn_reproducibility_note}
""".format(**reproducibility_notes, **tf32_notes)
这是一个展示所有元素的完整示例:
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
编写 PyTorch 文档字符串时,请确保:
r"""):func:, :class:, :meth:):class: 链接到相关模块类:class:\~torch.nn.Module`` - 类引用:func:\torch.function`` - 函数引用:meth:\~Tensor.method`` - 方法引用:attr:\attribute`` - 属性引用:math:\equation`` - 行内数学公式:ref:\label`` - 内部引用code - 行内代码(使用双反引号)True`` ``None`` ``FalseTensor、int、float、bool、str、tuple、list 等每周安装量
241
仓库
GitHub 星标数
98.5K
首次出现
2026年1月20日
安全审计
安装于
claude-code218
opencode216
gemini-cli214
cursor211
codex211
github-copilot199
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.
r"""...""") for all docstrings to avoid issues with LaTeX/math backslashesStart with the function signature showing all parameters:
r"""function_name(param1, param2, *, kwarg1=default1, kwarg2=default2) -> ReturnType
Notes:
* separator)Provide a one-line description of what the function does:
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.
Use Sphinx math directives for mathematical expressions:
.. math::
\text{Softmax}(x_{i}) = \frac{\exp(x_i)}{\sum_j \exp(x_j)}
Or inline math: :math:\x^2``
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~ prefix shows only the last component (e.g., Conv2d instead of torch.nn.Conv2d)Example:
See :class:`~torch.nn.Conv2d` for details and output shape.
Use admonitions for important information:
.. 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`.
Document all parameters with type annotations and descriptions:
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:
(Type), (Type, optional) for optional parametersvalue" at the endNoneSometimes keyword arguments are documented separately:
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``.
Document the return value:
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.
Always include examples when possible:
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:
Examples:: with double colon>>> prompt for Python code# when helpful>>>)Link to papers or external documentation:
.. _Link Name:
https://arxiv.org/abs/1611.00712
Reference them in text: See Link Name_
For regular Python functions, use a standard docstring:
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
For C-bound functions, use _add_docstr:
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)`
...
""",
)
For in-place operations (ending with _), reference the original:
add_docstr_all(
"abs_",
r"""
abs_() -> Tensor
In-place version of :meth:`~Tensor.abs`
""",
)
For aliases, simply reference the original:
add_docstr_all(
"absolute",
r"""
absolute() -> Tensor
Alias for :func:`abs`
""",
)
Use LaTeX math notation for tensor shapes:
:math:`(\text{minibatch} , \text{in\_channels} , iH , iW)`
For commonly used arguments, define them once and reuse:
common_args = parse_kwargs(
"""
dtype (:class:`torch.dtype`, optional): the desired type of returned tensor.
Default: if None, same as this tensor.
"""
)
# Then use with .format():
r"""
...
Keyword args:
{dtype}
{device}
""".format(**common_args)
Insert reproducibility notes or other common text:
r"""
{tf32_note}
{cudnn_reproducibility_note}
""".format(**reproducibility_notes, **tf32_notes)
Here's a complete example showing all elements:
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
When writing a PyTorch docstring, ensure:
r"""):func:, :class:, :meth:):class::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 referencecode - Inline code (use double backticks)True`` ``None`` ``FalseTensor, int, float, bool, str, tuple, list, etc.Weekly Installs
241
Repository
GitHub Stars
98.5K
First Seen
Jan 20, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
claude-code218
opencode216
gemini-cli214
cursor211
codex211
github-copilot199
超能力技能使用指南:AI助手技能调用优先级与工作流程详解
41,800 周安装