PyTorch Docathon 2026 刚落下帷幕，社区交出了 150+ 已合并 PR 的成绩单。一场围绕文档的冲刺活动，能吸引这么多人持续投入，本身就说明一件事——PyTorch 的文档痛点真实存在，而修复它的门槛比很多人想象的要低。
文档质量直接决定上手速度
PyTorch 的 API 数量庞大，从 torch.nn 到 torch.distributed，从 eager mode 到 TorchScript、torch.compile，每一层都有自己的概念和约定。文档是开发者与框架之间的接口，接口模糊，调试成本就飙升。
典型的痛点包括：参数描述缺失默认值含义、返回值类型只写了 Tensor 却没说明形状、示例代码跑不通因为遗漏了 import。这些看起来是"小问题"，但在深夜排查一个维度不对的 bug 时，一个准确的 docstring 能省下半小时。
Docathon 的 150+ PR 正是在修补这类裂缝——补参数说明、加运行示例、修正错别字、统一格式。每一笔改动可能只涉及几行文字，但累积效应显著。
什么样的文档改动最有价值
从历次 Docathon 的合并趋势看，高价值改动集中在三类：
补运行示例。 一个只有签名和参数列表的 API，开发者必须自己试才能确认行为。加上 3-5 行可运行代码，文档就从"说明书"变成"教程"。PyTorch 官方也越来越强调这一点，新 API 的 docstring 规范里明确要求附带 example。
修正形状与 dtype 描述。 张量操作最容易出歧义的地方是输出形状。torch.matmul 在不同输入维度下行为不同，文档如果只写"returns the matrix product"，读者只能靠猜。把每种维度组合的输出形状写清楚，比加一段抽象描述管用。
统一术语与链接。 同一篇文档里一会儿叫"tensor"一会儿叫"Tensor"，或者引用了已废弃的 API 而没有指向新替代，这类不一致会让初学者困惑。批量修正术语和补交叉链接，是 Docathon 里最常见的低门槛高回报任务。
实操：从发现问题到提交 PR
下面是一个完整的贡献流程，从本地构建文档到提交修改。假设你发现 torch.nn.functional.gelu 的 docstring 缺少一个直观的运行示例。
1. 克隆仓库并构建文档
# 克隆 PyTorch 仓库
git clone https://github.com/pytorch/pytorch.git
cd pytorch
# 安装文档构建依赖
pip install -r docs/requirements.txt
# 构建文档（首次构建较慢，后续增量构建很快）
cd docs
make html
# 构建完成后在浏览器查看
open build/html/index.html # macOS
# 或 xdg-open build/html/index.html # Linux
2. 定位并修改 docstring
PyTorch 的 API docstring 写在源码里，而非单独的 .rst 文件。F.gelu 的定义在 torch/nn/functional/activation.py：
# 用 grep 快速定位
grep -n "def gelu" torch/nn/functional/activation.py
找到函数后，在 docstring 的 Example 区块补上可运行代码：
def gelu(input: Tensor, approximate: str = "none") -> Tensor:
r"""
.. math::
\text{GELU}(x) = x * \Phi(x)
When ``approximate = 'tanh'``, uses the tanh approximation:
.. math::
\text{GELU}(x) = 0.5 * x * (1 + \tanh(\sqrt{2/\pi} * (x + 0.044715 * x^3)))
Args:
input (Tensor): The input tensor.
approximate (str, optional): The approximation algorithm to use:
``'none'`` or ``'tanh'``. Default: ``'none'``.
Returns:
Tensor: The output tensor with the same shape as input.
Examples::
>>> import torch
>>> x = torch.randn(4)
>>> torch.nn.functional.gelu(x)
tensor([ 0.1581, -0.0214, 0.4329, -0.0126])
>>> torch.nn.functional.gelu(x, approximate='tanh')
tensor([ 0.1580, -0.0214, 0.4328, -0.0126])
"""
关键细节：Examples:: 后面必须空一行，每行代码以 >>> 或 ... 开头，输出行不加前缀。PyTorch 的文档构建系统会自动提取这些示例并用 doctest 验证。
3. 本地验证并提交
# 重新构建文档，确认改动渲染正确
cd docs
make html
# 运行 doctest 验证示例代码（可选但推荐）
make doctest
# 回到仓库根目录，提交改动
cd ..
git add torch/nn/functional/activation.py
git commit -m "docs: add runnable example for F.gelu"
# 推送并创建 PR
git push origin my-doc-fix
# 然后在 GitHub 上创建 Pull Request，标题以 "docs:" 开头
提交 PR 时在描述里注明你验证了 doctest，维护者合并的速度会快很多。
参与下一次 Docathon 的准备清单
Docathon 通常每年举办一次，但文档贡献不限于活动期间——日常随时可以提 PR。如果你打算下次参与，这几步提前做：
- 本地构建环境提前搭好。
make html首次构建可能需要 10 分钟以上，活动当天再搭容易卡在依赖问题上。 - 熟悉 docstring 规范。 PyTorch 使用 NumPy 风格的 docstring，具体约定见仓库内
docs/CONTRIBUTING.md。 - 提前浏览未解决的文档 issue。 GitHub 上带
module: docs标签的 issue 是现成的任务清单，挑几个简单的心里有底。 - 跑一遍 doctest。
make doctest能暴露已有示例中的错误，这些错误就是现成的 PR 机会。
文档贡献的门槛比核心代码低得多——不需要深入理解 CUDA kernel 或 autograd 引擎，只需要你作为一个用户，把"自己踩过的坑"写清楚。150+ PR 已经证明了这条路可行，下一次轮到你的时候，一个示例、一行参数说明，就是最实在的贡献。