NumPy 文档贡献全指南：docstring、Doxygen 与 Diátaxis 框架实战手册-平芜编程栈

科学计算
数据分析

【免费下载链接】numpy

The fundamental package for scientific computing with Python.

项目地址：https://gitcode.com/gh_mirrors/nu/numpy

本指南以 NumPy 官方开发者文档 howto-docs.rst 为骨架，系统讲解如何为 NumPy 贡献文档：从识别文档缺口、修复 docstring 缺陷，到用 numpydoc 规范撰写 Python 文档字符串，再到用 Doxygen + Breathe + Sphinx 三件套为 C/C++ 核心代码撰写并渲染 API 文档，以及使用.. legacy::指令标注过期模块。读完本文，你将掌握一套完整、可落地、与 NumPy 源码树直接对应的文档贡献工作流。

文档团队会议与社区协作入口

NumPy 社区把改进文档当作明确目标，定期通过 Zoom 召开文档会议（会议日期通过 numpy-discussion 邮件列表公布），任何人均可参加。会议记录发布在 hackmd.io，并归档于 NumPy Archive 仓库。如果你需要有人带你完成第一次贡献，可以在会议上直接求助——这是新手入门最友好的渠道。

贡献文档不只有"写"一条路：报告文档缺陷同样是重要贡献。下文会分别介绍"修复缺陷"与"撰写新页面"两条路径，以及它们各自的技术规范。

修复文档缺陷：优先级与处理方式

缺陷的优先级排序

NumPy 希望优先修复那些"最值得投入"的文档问题，优先级如下：

技术性错误（最高优先级）：docstring 遗漏了某个参数、函数/参数/方法的描述有误等。这类缺陷容易确认、容易修正，且对用户价值最大。
结构性缺陷（次高优先级）：如文档中的失效链接（broken links）。
拼写错误：欢迎反馈，但可能无法被及时修复。
措辞问题：明显的措辞错误（如漏掉一个 "not"）归入拼写类；但其他改写——即便是语法层面的——需要判断力把关，门槛更高，建议先在 issue 中抛出方案、试探社区意见。

修复方式：如果你熟悉 GitHub 流程，直接提交 Pull Request（PR）；否则请先开 issue 说明问题。

C 扩展模块的 docstring 藏在哪儿

一个容易踩坑的细节：numpy.ndarray.transpose、numpy.array等定义在 C 扩展模块中的函数/对象，其 docstring 并不写在 C 源码里，而是单独定义在 numpy/_core/_add_newdocs.py中。因此，当你需要修正这类对象的文档时，应前往该文件修改对应的 Python 字符串，而不是去.c文件里找。这一设计在仓库中同样体现在_add_newdocs_scalars.py（标量类型文档）等配套文件上（参见 numpy/_core 目录），并在 meson.build 中参与构建。

贡献新页面：从想法到落地

你自己使用文档时的困惑，就是文档最需要改进的地方。

想写一篇缺失的文档：先到邮件列表征求意见，获取反馈后再动笔；
只想指出缺口：直接开 issue 即可（官方文档以 issue #15760 为例展示这种流程）。

如果你在寻找选题，正式的文档路线图是 NumPy Enhancement Proposal（NEP），即NEP 44（见 doc/source/neps 目录下的 nep-0044-restructuring-numpy-docs.rst）。它列出了文档需要帮助的领域和期望新增的内容，其中包括Jupyter Notebook 教程。

教程的独立投稿渠道：NumPy Tutorials

除了随源码树分发的文档外，你还可以把 Jupyter Notebook 格式的内容提交到 NumPy Tutorials 页面。这些教程和教学材料由 NumPy 项目维护，面向自学与课堂教学双重场景，开发工作在独立的 numpy-tutorials 仓库进行：可以查看现有 notebook、开 issue 提议新主题、或通过 PR 提交自己的教程。

文档框架：Diátaxis 四象限

编写实用文档有公式可循，四种公式几乎覆盖所有场景，因为文档恰好分为四种类型：

文档类型	定位
tutorial（教程）	面向初学者，通过一步步操作完成学习
how-to guide（操作指南）	面向有明确任务的使用者，解决具体问题
explanation（解释）	面向需要理解原理的读者，讲清"为什么"
reference（参考）	面向查证需求的用户，精确描述接口细节

这一洞察来自 Daniele Procida 的 Diátaxis 框架。开始撰写或提出一篇新文档时，先明确它属于哪一类——这决定了文档的结构、语气与目标读者。

其他贡献注意事项

语言与粗糙初稿：英语不是母语、只能写出粗略草稿都没关系，开源是社区协作，社区会帮你完善；
图片与真实数据：能显著增强文档表现力，但必须确保授权合规、可获取；
数据格式：目前 NumPy 只接受其他 Python 科学库（pandas、SciPy、Matplotlib）同样使用的数据格式；
提交方式：NumPy 文档保存在源码树中，要进入文档库，你需要拉取源码树、本地构建（详见下文"构建文档"），然后提交 PR。不熟悉 GitHub/PR 可以阅读仓库中的开发工作流文档；
标记语言：NumPy 文档使用reStructuredText（rST），比 Markdown 更复杂；Sphinx 负责将 rST 转换为 HTML 等格式。

间接贡献同样被认可

你在博客写教程、做 YouTube 视频、在 Stack Overflow 等网站回答问题，都算为 NumPy 做出了贡献；遇到适合补充进官方文档的外部材料，也可以通过 issue 告知维护者。

构建文档：本地验证你的修改

要让贡献被合并，本地必须能成功构建文档。构建前置要求如下：

NumPy 本体：文档很大一部分通过import numpy读取 docstring 生成，因此必须先构建并安装对应版本的 NumPy，且每次拉取最新源码后都要重新构建安装，保证 NumPy 版本与 git 仓库版本同步。可安装到临时目录并设置PYTHONPATH，或使用 conda/virtualenv/venv 新建虚拟环境安装。
依赖：除 Doxygen 外，所有依赖可用一条命令安装：

pip install -r requirements/doc_requirements.txt

必要时可安装文档依赖的开发版：

pip install --pre --force-reinstall --extra-index-url \ https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \ -r requirements/doc_requirements.txt

构建体系使用 Sphinx + Doxygen，另需 Matplotlib 自带的plot_directiveSphinx 扩展渲染示例图、numpydoc 渲染 docstring，SciPy 也被安装（部分文档章节依赖 SciPy 函数）。Doxygen 建议安装高于 1.8.10 的版本，否则构建时可能出现警告。 3.子模块：通过 git 获取的源码还需拉取子模块：git submodule update --init。

一切就绪后，一键构建：

spin docs

该命令会从源码构建 NumPy（如果尚未构建），并运行 Sphinx 生成 HTML 文档，输出到doc/build/html子目录。官方发布在 numpy.org/doc 的 HTML 与 PDF 文档则由make dist构建。详细流程参见如何构建 API 与参考文档。

文档风格：用户文档与 docstring 规范

用户文档风格

用户指南总体遵循Google developer documentation style guide；
Google 未覆盖或社区倾向不同之处，由NumPy 风格补充，当前规则包括：
- index的复数用indices而非indexes（沿用numpy.indices的先例）；
- 为保持一致，matrix的复数用matrices；
两者都未充分解决的语法问题，以最新版Chicago Manual of Style的 "Grammar and Usage" 章节为准；
社区欢迎随时指出应加入 NumPy 风格规则的案例。

docstring：必须使用 numpydoc 约定

使用 Sphinx 配合 NumPy 约定时，应启用numpydoc扩展，docstring 才能被正确处理。例如，Sphinx 会从 docstring 中提取Parameters章节并转换为字段列表；而纯 Sphinx 遇到 NumPy docstring 约定（如-------------式节标题）会产生 rST 错误，numpydoc 可以避免这些问题。

两条重要约定：

示例中无需import numpy as np：NumPy 文档内的示例默认已有 numpy 环境，不要画蛇添足；
格式必须遵循 numpydoc 的格式化标准与官方示例。

关于 docstring 中每个字段（Parameters、Returns、Raises、Examples 等）的写法，可进一步参考仓库中的 EXAMPLE_DOCSTRING.rst。

为 C/C++ 代码撰写文档：Doxygen + Breathe + Sphinx 三步走

NumPy 的核心（如numpy/_core/src/下的 C 实现）用Doxygen解析特殊格式的 C/C++ 注释块，生成 XML 文件，再由Breathe转换为 rST，最终由Sphinx渲染成 HTML。整个文档化流程分三步。

第一步：编写注释块

尚无强制规定的注释风格，但Javadoc 风格与现有未索引注释块更相似，因而更受青睐。Javadoc 风格示例如下（源码见 doc/source/dev/examples/doxy_func.h）：

/** * This a simple brief. * * And the details goes here. * Multi lines are welcome. * * @param num leave a comment for parameter num. * @param str leave a comment for the second parameter. * @return leave a comment for the returned value. */ int doxy_javadoc_example(int num, const char *str);

该函数在文档中通过.. doxygenfunction:: doxy_javadoc_example指令渲染。

对于行注释，可以使用三斜杠///，例如 doc/source/dev/examples/doxy_class.hpp 中的模板类：

/** * Template to represent limbo numbers. * * Specializations for integer types that are part of nowhere. * It doesn't support with any real types. * * @param Tp Type of the integer. Required to be an integer type. * @param N Number of elements. */ template<typename Tp, std::size_t N> class DoxyLimbo { public: /// Default constructor. Initialize nothing. DoxyLimbo(); /// Set Default behavior for copy the limbo. DoxyLimbo(const DoxyLimbo<Tp, N> &l); /// Returns the raw data for the limbo. const Tp *data(); protected: Tp p_data[N]; ///< Example for inline comment. };

该类的文档通过.. doxygenclass:: DoxyLimbo指令渲染。

常用 Doxygen 标签速查

标签	作用
`@brief`	开启一段简短描述段落。由于 Doxygen 配置中启用了`JAVADOC_AUTOBRIEF`，文档块的第一句话默认会被当作简短描述
`@details`	开启详细描述段落。也可以用空行开启新段落，此时无需`@details`
`@param`	描述函数参数。Doxygen 会校验参数是否存在，若某个参数缺少文档会给出警告
`@return`	描述函数返回值。相邻的多个`@return`会合并为一段，遇到空行或其他分节命令时结束
`@code/@endcode`	包裹代码块，代码块会按源代码而非普通文本解析
`@rst/@endrst`	包裹一段 reST 标记

@rst/@endrst的威力见 doc/source/dev/examples/doxy_rst.h：

/** * A comment block contains reST markup. * @rst * .. note:: * * Thanks to Breathe_, we were able to bring it to Doxygen_ * * Some code example:: * * int example(int x) { * return x * 2; * } * @endrst */ void doxy_reST_example(void);

第二步：喂给 Doxygen（.doxyfile 子配置文件）

Doxygen不会自动收集所有头文件，必须把需要处理的 C/C++ 头文件路径加进 Doxygen 的子配置文件中。这些子配置文件统一命名为.doxyfile，通常位于包含待文档化头文件的目录附近；如果距头文件 2 层深度内没有现成配置，需要新建一个。

子配置文件可以接受 Doxygen 的任何配置选项，但不能用=覆盖或重新初始化已有选项，只能用追加运算符+=。仓库中的真实子配置文件可以佐证这一约定，例如 doc/source/dev/examples/.doxyfile：

INPUT += @CUR_DIR INCLUDE_PATH += @CUR_DIR

其中@CUR_DIR是一个模板常量，返回子配置文件所在目录的路径。核心头文件目录的配置（numpy/_core/include/numpy/.doxyfile）展示了如何通过PREDEFINED为解析器预定义宏：

INCLUDE_PATH += @CUR_DIR PREDEFINED += NPY_INTERNAL_BUILD

而 numpy/_core/src/common/.doxyfile 则用于收集核心实现目录中的头文件。一个典型的子配置文件长这样：

# 指定某些头文件 INPUT += @CUR_DIR/header1.h \ @CUR_DIR/header2.h # 添加某路径下的所有头文件 INPUT += @CUR_DIR/to/headers # 定义某些宏 PREDEFINED += C_MACRO(X)=X # 启用某些条件编译分支 PREDEFINED += NPY_HAVE_FEATURE \ NPY_HAVE_FEATURE2

第三步：Breathe 包含指令（把 Doxygen 输出转成 rST）

Breathe 提供丰富的自定义指令，把 Doxygen 生成的文档转换为 rST 文件。常用指令如下。

doxygenfunction：为单个函数生成输出，函数名在项目中必须唯一：

.. doxygenfunction:: <function name> :outline: :no-link:

doxygenclass：为单个类生成输出，在标准 project/path/outline/no-link 选项之外，还支持 members、protected-members、private-members、undoc-members、membergroups 与 members-only 选项：

.. doxygenclass:: <class name> :members: [...] :protected-members: :private-members: :undoc-members: :membergroups: ... :members-only: :outline: :no-link:

doxygennamespace：为命名空间内容生成输出，额外支持 content-only、members、protected-members、private-members、undoc-members 选项。引用嵌套命名空间时必须给出完整路径，如foo::bar表示 foo 内的 bar 命名空间：

.. doxygennamespace:: <namespace> :content-only: :outline: :members: :protected-members: :private-members: :undoc-members: :no-link:

doxygengroup：为 Doxygen 分组生成输出（分组通过在源码注释中写特定 Doxygen 标记声明），额外支持 content-only、members、protected-members、private-members、undoc-members 与 inner 选项：

.. doxygengroup:: <group name> :content-only: :outline: :members: :protected-members: :private-members: :undoc-members: :no-link: :inner:

legacy 指令：标注过期 API

如果某个函数、模块或 API 处于legacy（遗留）模式——即为向后兼容而保留、但不建议在新代码中使用——可以在文档中使用.. legacy::指令。

无参数使用时，生成默认提示文案。该指令的实际渲染逻辑实现在 doc/source/conf.py 的LegacyDirective类中（第 172–221 行）：默认把对象当作submodule，生成类似 "This submodule is considered legacy and will no longer receive updates. This could also mean it will be removed in future NumPy versions." 的提示，并以 "Legacy" 为标题、套用admonition-legacyCSS 类渲染成警示块；
推荐附加自定义信息，例如指明替代的新 API，自定义内容会追加到默认文案之后：

.. legacy:: For more details, see :ref:`distutils-status-migration`.

可选参数用于指定遗留对象类型（函数、方法等），而非默认的 submodule：

.. legacy:: function

持续学习：文档写作资源

Write the Docs：领先的技术写作者组织，举办会议、提供学习资源、运营 Slack 频道；
Google 技术写作资源："Every engineer is also a writer"，提供面向开发者的免费在线课程，涵盖文档规划与写作；
Software Carpentry：面向研究人员的软件教学组织，其课程网站也系统讲解了如何有效呈现技术想法。

总而言之，为 NumPy 贡献文档是一条"从反馈到深度贡献"的递进路径：你既可以开 issue 报告缺陷，也可以直接修复_add_newdocs.py中的 C 扩展 docstring；既能按 Diátaxis 框架撰写教程与解释性文档，也能用 Javadoc 风格注释 +.doxyfile子配置 + Breathe 指令为 C/C++ 核心代码补齐 API 参考。所有修改最终都要经过本地spin docs构建验证后以 PR 提交——这正是 NumPy 文档保持高质量、可溯源的原因所在。