Apache MXNet 社区文档与教程写作指南：从 numpydoc、Doxygen 到 notedown 的完整规范

• 人工智能
• 深度学习
• 机器学习

本文是面向 Apache MXNet 贡献者的文档写作指南，系统讲解该项目文档体系的构建方式：Python 接口如何遵循 numpydoc 规范编写 docstring、C++ 接口如何遵循 Doxygen 格式注释、Jupyter 教程如何以 Markdown 编写并通过 notedown 在构建服务器上执行生成页面，以及深度学习的应用示例如何被 CI 持续校验。读完本文，你将掌握向 MXNet 仓库提交高质量文档与教程的全部规范与本地构建验证方法。

MXNet 文档体系概览：Sphinx 为骨架，reStructuredText 优先

MXNet 的主文档使用 Sphinx 构建。Sphinx 同时支持 reStructuredText（RST）和 Markdown 两种源格式，但官方规范明确：

• 尽可能优先使用 reStructuredText，因为它拥有更丰富的指令与排版能力；
• Markdown 主要用于教程等场景（配合 notedown 使用，详见后文）；
• Python 的 docstring 与教程文件本身允许嵌入 reStructuredText 语法，从而让 Sphinx 在渲染时获得交叉引用、卡片布局等增强能力。

该策略在仓库中的实际落点非常清晰：docs/python_docs/python 目录下，index.rst、api/index.rst与各模块的.rst文件构成 API 参考的骨架，而tutorials/目录下则同时存在.rst（如tutorials/index.rst）与.md（如tutorials/getting-started/logistic_regression_explained.md）两种来源。

以 docs/python_docs/python/api/index.rst 为例，可以看到 MXNet 对 API 文档的分层组织方式：命令式 API（mxnet.np、mxnet.npx、mxnet.gluon）、Gluon 相关模块（mxnet.autograd、mxnet.optimizer、mxnet.kvstore、mxnet.device、mxnet.profiler等）、高级模块（mxnet.runtime、mxnet.executor、mxnet.engine、mxnet.rtc、mxnet.test_utils等）以及 Legacy 模块（mxnet.ndarray、mxnet.symbol、mxnet.image、mxnet.io、mxnet.recordio、mxnet.visualization）。这种用 RSTcard指令组织的目录结构，就是"以 reStructuredText 承载丰富特性"的直接体现。

编写 Python 文档：遵循 numpydoc 格式

MXNet 使用 numpydoc 格式为函数和类编写 docstring。numpydoc 是科学计算社区广泛采用的 docstring 规范，其核心价值在于：结构化的小节标题（如Parameters、Returns、Examples）能被 Sphinx 的 autodoc 扩展解析并渲染为排版一致的 API 参考页面。

标准 docstring 模板

仓库官方规范给出的示例模板如下：

def myfunction(arg1, arg2, arg3=3): """Briefly describe my function. Parameters ---------- arg1 : Type1 Description of arg1 arg2 : Type2 Description of arg2 arg3 : Type3, optional Description of arg3 Returns ------- rv1 : RType1 Description of return type one Examples -------- .. code:: python # Example usage of myfunction x = myfunction(1, 2) """ return rv1

对照该模板，需要注意以下规范要点：

• 必须为所有公开函数编写文档。公开 API 是文档面向用户的门面，任何新增的公开函数都应当有 docstring；
• 参数小节格式：每个参数一行，采用参数名 : 类型的缩进式冒号语法，下一行缩进书写描述；带默认值的参数标记为optional；
• 返回值小节：Returns小节同样采用名称 : 类型格式，多返回值时逐行列出；
• 示例小节：Examples中通过 RST 指令.. code:: python内嵌可执行的 Python 代码块。规范特别强调：在支持的功能有必要时，务必提供使用示例（正如模板所示），这能显著提升文档的实战价值；
• 小节之间的空行至关重要：在Parameters、Returns和Examples等小节标题之前必须保留空行，否则文档构建时解析会出错。这一点在 Sphinx/numpydoc 的解析机制下是硬性要求。

如何把新函数挂载到文档

仅有 docstring 还不够——要让新函数出现在 API 参考中，还需要把函数接入 Sphinx 的 autodoc 机制：

1. 在 docs/python_docs/python 目录下为对应模块添加或修改 RST 文件；
2. 在该 RST 文件中编写sphinx.autodoc规则（即.. automodule::/.. autofunction::等指令）；
3. 可以参考该目录下已有文件的写法来添加新函数。

以 docs/python_docs/python/api/index.rst 为例，其末尾通过.. toctree::配合:glob:模式将np/index、npx/index、gluon/index、autograd/index等模块索引统一纳入文档树，这正是 autodoc 规则在项目中的组织方式。

仓库中真实的 docstring 实践遍布整个 Python 源码，例如 python/mxnet 下的ndarray、symbol、gluon等模块，均可作为编写时的参照样本。此外，docs/python_docs/python下的requirements文件列出了构建文档所需的 Python 依赖（含 numpydoc、sphinx 等），是本地构建的前提。

编写 C++ 文档：遵循 Doxygen 格式

对于 C++ 代码，MXNet 使用 Doxygen 注释格式。规范给出的示例模板如下：

/*! * \brief Description of my function * \param arg1 Description of arg1 * \param arg2 Description of arg2 * \returns describe return value */ int myfunction(int arg1, int arg2) { // When necessary, also add comment to clarify internal logic }

要点说明：

• 注释块以/*!开头，这是 Doxygen 识别文档注释块的标志；
• \brief提供一句话函数简介；
• \param 参数名 描述逐参数说明；
• \returns描述返回值；
• 除函数用法注释外，规范强烈建议贡献者为内部代码逻辑添加注释，以提升可读性——尤其是涉及算法、内存管理或并发逻辑的复杂实现。

仓库的 C++ 文档构建配置位于 docs/cpp_docs/Doxyfile，其中PROJECT_NAME = "mxnet"等配置项定义了 Doxygen 生成 C++ API 文档的项目元信息。在公开头文件 include/mxnet 下，c_api.h、base.h、api_registry.h等文件中大量使用了\brief、\param、\returns指令，是上述格式的真实落地范例，编写新 C++ 接口时可以照此风格对齐。

编写教程：用 notedown 以 Markdown 写 Jupyter 教程

MXNet 的 Python 教程采用一种轻量而高效的工作流：使用 notedown 把 Markdown 编写的教程当作 Jupyter notebook 来写。

教程源码位置

教程源文件位于 docs/python_docs/python/tutorials，按主题划分为deploy/（部署）、extend/（扩展）、getting-started/（入门，含 crash-course 与迁移指南等）、packages/（各语言/框架包）与performance/（性能）等子目录。

Markdown 教程如何变成可执行 notebook

教程代码会在项目的构建服务器上执行，生成文档页面，教程页会展示执行 Jupyter notebook 后的真实输出结果。也就是说，教程中每个 Markdown 代码块都会被当作 notebook 单元执行，教程代码必须真实可运行，构建阶段就会暴露错误。

这一机制在 docs/python_docs/python/Makefile 中有清晰实现：

• IPYNB_MARKDOWN通过find收集所有.md文件（排除build/与*.ipynb_checkpoints*）；
• 规则build/%.ipynb: %.md调用python3 scripts/md2ipynb.py $< $@，把 Markdown 教程转换为.ipynbnotebook；
• RST文件则被直接复制到build/目录。

因此，撰写教程的贡献者只需要维护.md源文件，构建流水线会自动完成md → ipynb → 执行 → 渲染 HTML的转换链。

本地体验教程运行效果

如需在本地直接运行 Markdown 教程（而不构建完整站点），docs/python_docs/README.md 给出了基于 notedown 的 Jupyter 运行方案：

1. 在远程服务器安装 notedown 插件：pip install https://github.com/mli/notedown/tarball/master；
2. 以 notedown 作为 contents manager 启动 Jupyter：jupyter notebook --NotebookApp.contents_manager_class='notedown.NotedownContentsManager'；
3. 通过端口转发访问：ssh -L8888:localhost:8888 your_machine；
4. 浏览器打开http://localhost:8888后即可直接运行.md文件。

若希望一劳永逸地自动启用该插件，可以执行jupyter notebook --generate-config生成配置文件，然后在~/.jupyter/jupyter_notebook_config.py中添加一行：

c.NotebookApp.contents_manager_class = 'notedown.NotedownContentsManager'

之后直接运行jupyter notebook即可把 Markdown 教程当 notebook 打开执行。

本地构建文档站点（含教程执行）

同样依据 docs/python_docs/README.md，本地构建文档的流程为：

前置条件

• 完整构建（含执行全部教程）通常需要 GPU 环境（默认配置要求 GPU + CUDA 9.2，预期 Ubuntu 系统；macOS/Windows 也可配置无 GPU 的构建）；
• 运行全部教程需要至少两块 GPU，因为分布式训练是 MXNet 的核心特性，部分教程依赖多 GPU；
• 先按源码编译指南安装 MXNet，再安装 docs/python_docs/requirements 中列出的 Python 依赖：

python3 -m pip install -r requirements

构建命令

• 快速构建（不执行 notebook 测试，无需 GPU）：

make EVAL=0

• 完整构建（执行 notebook 测试，需要 GPU）：

make

构建产物输出在build/_build/html目录。即使不做执行验证，单次构建也可能耗时数分钟，可通过两种方式加速：在build/conf.py的exclude_patterns中加入要跳过的目录（如['templates', 'api', 'develop', 'blog']），或把不需要的文件移出构建目录后执行make clean。

查看构建结果

cd build/_build/html; python -m http.server

远程机器查看时用ssh -L8000:localhost:8000 your_machine做端口转发，然后在本地打开http://localhost:8000。

应用示例：独立仓库维护 + CI 持续校验

深度学习应用示例（Application Examples）与核心教程分开维护，由 CI 定期检查以保证质量。这意味着提交示例代码时，需要确保其可复现、可运行，并且与当前仓库的核心 API 保持同步——CI 的定期检查机制会拦截那些因 API 变更而过期的示例。

这一规范与仓库内文档 CI 的自动化理念一脉相承：无论是 docstring 还是教程，最终都会经过构建/执行环节的验证，贡献者"写文档"与"写可运行代码"是同一件事的两面。

小结：贡献 MXNet 文档的检查清单

写作完成后的标准验证路径是：先在本地按 docs/python_docs/README.md 完成pip install -r requirements与make EVAL=0的快速构建，确认 docstring 与 RST 能正确渲染；涉及教程改动时再用完整make验证 notebook 执行无误。这样提交的文档既能通过 CI 校验，也能为社区读者提供稳定、可复现的参考。

• 人工智能
• 深度学习
• 机器学习