document-public-apis

记录公共 API

此技能用于记录 PyTorch 中未记录的公共 API：从 docs/source/conf.py 中的覆盖率忽略列表移除条目，并在 docs/source/ 中相应的 .md 或 .rst 文档源文件里添加 Sphinx autodoc 指令（例如 autosummary、currentmodule、autoclass、automodule）。

“记录”是指向文档源文件添加 autodoc 指令——绝不要修改 Python 源代码。 不要在 .py 文件中添加或编辑文档字符串。你唯一要做的，就是在正确的文档文件中添加正确的指令。

重要：将任何函数添加到 Sphinx 文档树之前，务必确认它有实际的文档字符串。 使用快速的 Python 检查（例如 python -c "from torch.module import func; print(bool(func.__doc__))"），确认函数包含实际文档内容，而不只是空文档字符串，或仅有 .. warning:: This API is experimental 的占位内容。没有实质性文档字符串的函数应继续留在 coverage_ignore_functions/coverage_ignore_classes 列表中。将没有文档的函数添加到文档树会生成空白或内容极少的页面，降低文档质量。

概述

docs/source/conf.py 中有两个列表，用于抑制未记录 API 的 Sphinx 覆盖率警告：

• coverage_ignore_functions：未记录的函数
• coverage_ignore_classes：未记录的类

条目按模块注释组组织。每组都以模块标签注释开头，后面列出属于该模块的函数/类名称：

coverage_ignore_functions = [
    # torch.ao.quantization.fx.convert              <-- module label comment
    "convert",                                       # <-- entries belonging to this module
    "convert_custom_module",
    "convert_standalone_module",
    "convert_weighted_module",
    # torch.ao.quantization.fx.fuse                 <-- next module group
    "fuse",
    # torch.nn.functional
    "assert_int_or_pair",  # looks unintentionally public   <-- entry with inline comment
    "constant",  # deprecated                                <-- entry with inline comment
]

注释分为两种：

• 模块标签注释（# torch.ao.quantization.fx.convert）：标明下方条目所属的模块。它们单独占一行，位于一组条目前。
• 行内注释（# deprecated、# documented as adaptive_max_pool1d）：位于同一行的字符串条目之后，说明该条目为何被列入忽略列表。

模块标签注释会直接告诉你：

1. 函数所属的模块
2. 应将它们添加到文档中的哪个位置（例如，# torch.ao.quantization.fx.convert → 将函数添加到文档文件中 torch.ao.quantization.fx.convert 对应的位置）

操作说明

每次调用此技能都会处理一批模块组。从忽略列表中选取一个或多个完整模块组，记录其中的函数并进行验证。

第 1 步：选择要记录的模块组

阅读 docs/source/conf.py，并选择一个或多个完整模块组进行记录。模块组由模块标签注释及其下方直到下一个模块标签注释之前的所有条目组成。处理整个组——绝不要将一个组拆分到不同批次中。

例如，选择 torch.ao.quantization.fx.convert 组，就意味着要处理以下所有条目：

# torch.ao.quantization.fx.convert
"convert",
"convert_custom_module",
"convert_standalone_module",
"convert_weighted_module",

按列表从上到下处理。选择足够多的组以取得有意义的进展（目标为总计 5–15 个函数，但始终要包含完整的组，即使这意味着略微超出数量）。

纳入条目之前，请检查行内注释。 某些条目的行内注释表示不应记录：

• # deprecated — 函数已弃用。将其留在忽略列表中。
• # documented as <other_name> — 已使用其他名称记录。保留该条目。
• # looks unintentionally public — 该 API 可能并非有意公开。保留该条目。
• # legacy helper for ... — 与已弃用的情况相同。保留该条目。
• # utility function - 保留该条目。

如果模块组中既有普通条目，也有带行内注释的条目，仍应处理该组——但只注释掉普通条目。带行内注释的条目应继续留在忽略列表中。

步骤 1b：确认函数有实际的文档字符串

对于步骤 1 中选出的每个函数，运行以下命令，检查它是否有有意义的文档字符串：

python -c "from torch.module.path import func_name; doc = func_name.__doc__; print('HAS DOC' if doc and len(doc.strip()) > 80 else 'NO DOC'); print(repr(doc[:120]) if doc else 'None')"

如果文档字符串包含实际的描述性内容，则视为有意义的文档字符串，以下情况除外：

• None 或空字符串
• 仅包含没有描述内容的 .. warning:: This API is experimental 占位内容
• 仅包含一行自动生成的签名

没有有意义文档字符串的函数必须保留在忽略列表中。 将它们从本批次中移除。如果某个模块组中的函数都没有文档字符串，则跳过整个模块组。

步骤 2：向用户展示本批次内容

进行任何编辑之前，先向用户展示选定的模块组及其函数。说明哪些函数通过了文档字符串检查，哪些被排除。按模块整理展示：

Module: torch.ao.quantization.fx.convert
  - convert
  - convert_custom_module
  - convert_standalone_module
  - convert_weighted_module

Module: torch.ao.quantization.fx.fuse
  - fuse

然后使用 AskUserQuestion 工具让用户确认，并提供类似以下选项：

• “继续处理此批次”
• “跳过部分条目”（用户可以指定要移除的条目）
• “选择其他批次”

步骤 3：在 conf.py 中注释掉条目

用户确认后，编辑 docs/source/conf.py，将选定条目注释掉（不要删除）。在每个字符串条目前加上 # 前缀：

# torch.ao.quantization.fx.convert
# "convert",
# "convert_custom_module",
# "convert_standalone_module",
# "convert_weighted_module",

这样可以保留原始条目，以便在验证失败时恢复。

步骤 4：运行 Sphinx 覆盖率检查

cd docs && make coverage

忽略 make coverage 的终端输出。 输出中经常包含与覆盖率无关的 Sphinx 扩展（例如 onnx_ir、katex、sphinxcontrib）的回溯和错误。唯一重要的是是否生成了 docs/build/coverage/python.txt。读取该文件，查看具体未记录文档的 API。

python.txt 按以下格式列出每个未记录文档的 API：

torch.ao.quantization.fx.convert
   * convert
   * convert_custom_module
   * convert_standalone_module
   * convert_weighted_module

并非所有被注释掉的函数都会出现在 python.txt 中。 有些函数可能已在其他位置记录文档。这没有问题——只为实际出现在 python.txt 中的函数添加指令。

如果因缺少依赖项导致 make coverage 失败，请先运行：

cd docs && pip install -r requirements.txt

步骤 5：添加文档指令

对于 python.txt 中列出的每个函数，使用 conf.py 中的模块标签注释确定应将其添加到何处。模块注释提供完整的模块路径，可据此找到对应的文档源文件及其所在章节。

查找正确的文档文件

模块注释对应 docs/source/ 中的一个文档源文件。如不确定，请搜索同一模块中的其他函数：

grep -rn "torch.module_name" docs/source/*.md docs/source/*.rst

或者列出候选文件：

ls docs/source/*module_name*

如果某个子模块没有文档文件，请检查父模块的文档文件中是否有对应章节（例如，backends.md 中有 torch.backends.cuda、torch.backends.cudnn 等章节）。如果没有，请按照现有模式在父文件中添加新章节。

添加指令

先阅读目标文档文件，并遵循其中已使用的确切格式。不要自行创建新格式，也不要对完整限定名称直接使用 autofunction——始终使用包含 automodule、currentmodule 和短名称的正确层级结构。不要使用 . py:module::，因为它只会屏蔽错误，并不会真正记录函数。查看 docs/source/ 下与目标文件格式相同的其他文件（例如，.md 与 .rst），以了解示例。

文件有两种格式。请与目标文件使用的格式保持一致。

**模式 A — MyST Markdown 文件（.md）：**用于 accelerator.md、backends.md、cuda.md 等文件。

层级结构使用 automodule 注册模块，使用 currentmodule 设置上下文，然后使用短名称：

## torch.ao.quantization.fx.convert

```{eval-rst}
.. automodule:: torch.ao.quantization.fx.convert

.. currentmodule:: torch.ao.quantization.fx.convert

.. autofunction:: convert

.. autofunction:: convert_custom_module

For `autosummary` blocks (used in some files instead of individual directives):

```markdown
```{eval-rst}
.. autosummary::
    :toctree: generated
    :nosignatures:

    existing_function
    your_new_function
`` `

对于类：

```{eval-rst}
.. autoclass:: YourClass
    :members:
`` `

**模式 B — reStructuredText 文件（.rst）：**用于 torch.rst、nn.rst 等文件。

使用相同的层级结构，但不带 Markdown 围栏：

torch.ao.quantization.fx.convert
---------------------------------

.. automodule:: torch.ao.quantization.fx.convert

.. currentmodule:: torch.ao.quantization.fx.convert

.. autosummary::
    :toctree: generated
    :nosignatures:

    convert
    convert_custom_module
    convert_standalone_module
    convert_weighted_module

单个指令：

.. automodule:: torch.submodule

.. currentmodule:: torch.submodule

.. autofunction:: function_name

.. autoclass:: ClassName
    :members:

关键规则：

• conf.py 中的模块标签注释（例如，# torch.ao.quantization.fx.convert）会明确告诉你应使用哪个 automodule 和 currentmodule。
• 记录模块中的函数之前，务必先设置 .. automodule:: 和 .. currentmodule::。
• 设置 currentmodule 后，使用短名称（例如，convert，而不是 torch.ao.quantization.fx.convert.convert）。
• 如果文件中已经有该模块的 automodule/currentmodule，不要重复添加——直接在现有指令下添加函数即可。
• 遵循文件已有的风格（autosummary 块或单独的 autofunction 指令）。

放置到正确的章节

阅读目标文档文件并找到合适的章节。如果该模块已有章节（例如，backends.md 中的 ## torch.backends.cuda），就在该章节添加函数。如果还没有对应章节，则按照文件中已有的章节格式创建一个。将属于同一模块组的所有函数放在一起。

步骤 6：通过覆盖率验证

再次运行覆盖率检查：

cd docs && make coverage

忽略终端输出——只读取 docs/build/coverage/python.txt。当 python.txt 中所有模块均没有未记录的函数时，验证通过。文件中应只包含统计表，并且每个模块的覆盖率均为 100%、未记录数量均为 0。例如：

Undocumented Python objects
===========================

Statistics
----------

+---------------------------+----------+--------------+
| Module                    | Coverage | Undocumented |
+===========================+==========+==============+
| torch                     | 100.00%  | 0            |
+---------------------------+----------+--------------+
| torch.accelerator         | 100.00%  | 0            |
+---------------------------+----------+--------------+

如果任何模块仍有未记录的函数（覆盖率低于 100% 或未记录数量大于 0），则验证失败。

**如果验证成功（所有模块均无未记录的函数）：**转到步骤 7。

**如果验证失败（仍有未记录的函数）：**阅读 docs/build/coverage/python.txt，查看仍被列为未记录的函数。常见问题包括：

• 文档文件错误：函数被添加到了错误的 .md/.rst 文件中。将指令移到正确的文件。
• 指令类型错误：例如，对类使用了 autofunction，或对函数使用了 autoclass。修正指令。
• 指令中的模块路径错误：例如，torch.foo.bar 应为 torch.foo.baz.bar。修正限定名称。
• 函数被添加到了 currentmodule 错误的 autosummary 块中：确保块上方的 .. currentmodule:: 指令匹配。
• 尚未注册的子模块缺少 automodule：在记录该子模块的函数之前，添加 .. automodule:: torch.submodule 指令。

根据错误修正文档指令，然后重新运行 make coverage。重复此过程，直到验证通过。

如果多次尝试后函数仍未通过，**请停止并向用户展示错误。**提供函数名称和错误，然后使用 AskUserQuestion 工具，并给出类似以下选项：

• “取消注释，将其恢复到忽略列表（暂时跳过）”
• “尝试其他方法”
• “进一步调查”

步骤 7：报告进度

向用户提供进度摘要，说明：

• 已处理的模块组，以及已记录的函数数量
• 跳过或恢复到忽略列表中的函数（以及原因）
• coverage_ignore_functions 和 coverage_ignore_classes 中剩余的条目数

步骤 8：清理 conf.py 中注释掉的条目

现在验证已通过，请删除步骤 3 中注释掉的字符串条目。这些条目是 coverage_ignore_functions 和 coverage_ignore_classes 中以 # " 开头的行。注释掉的字符串条目始终包含引号，可据此与模块标签注释区分：

# "disable_global_flags",       <-- commented-out string entry (has quotes) → DELETE
# torch.backends                <-- module label comment (no quotes) → KEEP if it has active entries

还要删除下方没有活动条目的模块标签注释（即其所有条目都已被注释掉并删除，或者带有行内注释而保留，但该模块标签下已无其他条目）。

重要说明

• 严格按照步骤执行。 make coverage 步骤是验证 Sphinx 指令是否正确的主要方式，而步骤 1b 的文档字符串检查可确保你只为包含实际内容的函数编写文档。
• 绝不要修改 Python 源文件（.py）。 此技能只编辑 docs/source/conf.py 和 docs/source/ 中的文档源文件（.md/.rst）。不要添加或编辑文档字符串。检查 Python 模块的唯一目的是在步骤 1b 中确认是否存在文档字符串；绝不要修改源代码。
• 步骤 3 中的条目会被注释掉，在步骤 6 中验证，并在验证通过后于步骤 8 中清理。绝不要直接删除未注释的条目。
• 在决定是否为条目编写文档之前，先阅读行内注释。 标记为 # deprecated、# documented as ...、# looks unintentionally public 或 # legacy helper 的条目应保留在忽略列表中。
• coverage_ignore_functions 列表使用未限定的函数名（而非完全限定名），因此不同模块中可能多次出现同名函数。使用每个条目上方的模块标签注释来确认它所属的模块。步骤 8 清理时务必谨慎，只删除正确的注释行——注释掉的字符串条目带有引号（# "func_name",），模块标签注释则没有。
• 始终遵循目标文档文件现有的风格——不要在 .rst 文件中混用 .md 风格的指令，反之亦然。
• 使用模块标签注释（例如 # torch.ao.quantization.fx.convert）作为 automodule/currentmodule 指令以及在文档文件中查找相应章节的主要依据。
• 始终处理完整的模块组——绝不要在多次调用之间拆分同一组。