企业官网建设流程全解析

Apache TVM 文档写作指南：基于 Divio 体系的四类文档组织与 Sphinx 构建实践

【免费下载链接】tvmOpen deep learning compiler stack for cpu, gpu and specialized accelerators项目地址: https://gitcode.com/gh_mirrors/tvm7/tvm

Apache TVM 是一个面向 CPU、GPU 与专用加速器的开源深度学习编译器栈，其官方文档体系庞大且分层清晰。本文以仓库中的 docs/contribute/document.rst 为核心骨架，系统讲解 TVM 文档的组织方式（入门教程、操作指南、参考、架构指南四类文档）与写作规范（numpydoc、Doxygen、Sphinx Gallery），并结合 docs/README.md 与 docs/conf.py 给出从零构建文档的完整流程。读完本文，你将掌握为 TVM 撰写高质量文档、将其接入现有 Sphinx 构建体系并本地验证的全部能力。

文档体系设计：为什么采用 Divio 四类文档模型

TVM 的文档组织松散地遵循 Divio 提出的“正式文档风格”（formal documentation style），选择这一体系是因为它"简单、全面且几乎普遍适用，已在广泛的领域与应用中得到实践验证"。

整套体系将文档划分为四种类型，每种类型回答不同的问题、面向不同的读者、承担不同的职责。理解这一分类是撰写 TVM 文档的第一步，因为你写下的每一份文档都应当能被明确归类，并遵循该类型对应的写作约束。

入门教程（Introductory Tutorials）

入门教程是带领新用户逐步了解项目的手把手指南，其核心目标不一定是解释软件为什么这样工作——这些解释可以留给其他文档类型，而是促成一次成功的首次体验。它是把"围观者"转化为"用户与开发者"的最重要文档类型。

一段完整的端到端教程——从安装 TVM 与配套 ML 软件，到创建并训练模型，再到编译到不同架构——能让新用户以最高效的方式上手 TVM。教程教给初学者"他们需要知道的东西"，这与操作指南不同：操作指南回答的是"有一定经验的用户会提出的问题"。

关键要求是：教程必须可重复、可靠。因为一旦失败，用户就会转而寻找其他解决方案。

操作指南（How-to Guides）

操作指南是解决特定问题的分步指引。用户提出有意义的问题，文档给出答案。TVM 中的典型示例包括："如何为 ARM 架构编译优化模型？""如何编译并优化 TensorFlow 模型？"

这类文档应当足够开放，让用户能够看到如何将其迁移到新的用例上。实用性优先于完备性，标题应当直接告诉读者该操作指南解决的是什么问题。

教程与操作指南的区别在于：教程面向新开发者，聚焦于成功引入软件与社区，假设读者没有前置知识；操作指南假设读者具备最低限度的知识，目标是引导其完成特定任务。

参考（Reference）

参考文档描述软件如何被配置和运行，API、关键函数、命令与接口都是参考文档的候选内容。它们是让用户构建自己的接口和程序的"技术手册"，以信息为导向，聚焦于清单与描述。

可以假设参考文档的读者已经掌握软件的工作原理，正在寻找特定问题的特定答案。理想情况下，参考文档的结构应与代码库保持一致，并且尽可能自动生成（这正是 TVM 使用 Sphinx autodoc 的原因，详见下文）。

架构指南（Architecture Guides）

架构指南提供某一主题的背景与解释材料，帮助读者理解应用环境：为什么事情是这个样子的？当时做了哪些设计决策？考虑过哪些替代方案？描述现有系统的 RFC 是什么？

这类文档还包括与软件相关的学术论文与出版物链接，可以探讨相互矛盾的观点，帮助读者理解软件"为什么"以及"如何"被构建成现在这个样子。它不是操作指南或任务描述的场所，而应聚焦于帮助理解项目的高层概念。通常由项目的架构师和开发者撰写，但同样有助于用户与开发者深入理解软件的工作原理，并以与底层设计原则一致的方式参与贡献。

TVM 的特殊考量：用户/开发者分流与专题指南

TVM 社区有两个特殊考量，需要偏离 Divio 的简单文档风格。

第一个考量是用户社区与开发者社区经常重叠。许多项目用两套独立系统分别记录开发者体验与用户体验，但 TVM 适合在同一套系统中同时考虑两者，并在合适之处加以区分。因此，教程与操作指南被分为两类：

• 用户指南（User Guides）：聚焦用户体验；
• 开发者指南（Developer Guides）：聚焦开发者体验。

第二个考量是 TVM 社区中存在值得额外关注的特殊主题，包括但不限于 microTVM 与 VTA。可以为它们创建专门的专题指南（Topic Guides），用于索引已有材料，并提供如何最有效地导航这些材料的上下文。仓库中对应的专题目录可见于 docs/topic/microtvm 与 docs/topic/vta。

此外，为方便新人，TVM 还规划了专门的Getting Started 板块，包含安装说明、为什么使用 TVM 的概述以及其他首次体验文档。

技术细节：Sphinx 构建与写作规范

TVM 主文档使用Sphinx构建。Sphinx 同时支持 reStructuredText 与 Markdown，但在可能的情况下鼓励使用 reStructuredText，因为其特性更丰富。需要注意的是，Python 的 docstring 与教程中也可以嵌入 reStructuredText 语法。

仓库证据：docs/conf.py 中source_suffix = [".rst", ".md"]，即两种后缀都被 Sphinx 接受；同时启用了sphinx.ext.autodoc、sphinx.ext.autosummary、sphinx.ext.intersphinx、sphinx.ext.napoleon、sphinx.ext.mathjax、sphinx_gallery.gen_gallery与autodocsumm等一系列扩展。

Python 参考文档：numpydoc 规范

TVM 使用numpydoc格式编写函数与类的 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

写作时有几个容易被忽略的细节：

• 各部分之间必须保留空行：在上例中，Parameters、Returns、Examples之前都必须有空行，否则文档无法被正确构建；
• 新增函数进入文档的方式：需要在 docs/reference/api/python 中添加sphinx.autodoc规则。该目录下每个.rst文件即一个 API 参考页，例如 docs/reference/api/python/tir.rst 中通过.. automodule:: tvm.tir配合:members:、:imported-members:、:exclude-members:、:autosummary:等选项自动生成tvm.tir、tvm.tir.transform、tvm.tir.analysis、tvm.tir.stmt_functor的完整 API 文档。新增函数时，可参照该目录下已有文件的做法。

C++ 参考文档：Doxygen 规范

C++ 函数使用Doxygen格式记录，模板如下：

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

除了记录函数用法，TVM 还强烈建议贡献者为代码逻辑添加注释以提升可读性。C++ 侧文档的构建配置可在 docs/Doxyfile 中查看。

Sphinx Gallery 的 How-To

TVM 使用sphinx-gallery构建大量 Python how-to 文档，源码位于 gallery 目录下。一个值得注意的要点是：注释块使用 reStructuredText 而非 Markdown 编写，因此要留意语法差异。以 gallery/tutorial/introduction.py 为例，其正文以"""..."""docstring 与#注释块承载 reStructuredText 指令（如.. image::、:width:等），由 sphinx-gallery 在构建时提取并渲染为文档页面。

how-to 代码会在构建服务器上实际运行以生成文档页面，因此可能面临限制，例如无法访问远程的 Raspberry Pi。此时应在教程中添加一个标志变量（例如use_rasp），让用户只需修改一个标志即可轻松切换到真实设备，并在现有环境下演示用法。

如果新增了一个 how-to 分类，需要在 docs/conf.py 的examples_dirs/gallery_dirs列表以及 how-to 索引页（docs/how_to/index.rst）中添加引用。以 docs/conf.py 为例，它把gallery/tutorial、gallery/how_to/compile_models、gallery/how_to/deploy_models等源码目录与tutorial、how_to/compile_models、how_to/deploy_models等生成目录一一映射。

文档内交叉引用：使用 :ref: 标记

请使用 Sphinx 的:ref:标记来引用同一文档中的其他位置：

.. _document-my-section-tag: My Section ---------- You can use :ref:`document-my-section-tag` to refer to My Section.

这种方式比硬编码章节编号或 URL 更健壮——重构章节顺序或标题时，交叉引用依然有效。

带图片/图形的文档

reStructuredText 的figure与image元素允许文档包含图片 URL。TVM 文档的图片文件存在一个规范要求：

• 为 TVM 文档创建的图片文件应存放在独立的 web-data 仓库中；
• 使用这些图片的.rst文件则存放在 TVM 主仓库中。

这意味着通常需要两个 Pull Request：一个提交图片文件，另一个提交.rst文件，贡献者与评审者之间可能需要讨论以协调评审流程。

重要提示：当使用上述两个 PR 时，请先合并 web-data 仓库中的 PR，再合并 TVM 仓库中的 PR，这样才能保证 TVM 在线文档中的所有 URL 链接始终有效。

本地构建文档的完整流程

按 docs/README.md 的说明，TVM 文档可以在本地以 Docker（推荐）或原生方式构建。

Docker 方式（推荐）

在 tlcpack/ci-gpu 脚本：

# 如果报错，尝试清理 'build' 目录 python tests/scripts/ci.py docs # 查看其他文档构建选项 python tests/scripts/ci.py docs --help

构建完成后启动 HTTP 服务，浏览器访问 http://localhost:8000 查看文档：

python tests/scripts/ci.py serve-docs

原生构建方式

1. 先在仓库根目录构建 TVM；

2. 安装依赖（Ubuntu 上 Pillow 可能需要 apt 安装 libjpeg-dev）：

   ./docker/bash.sh ci_gpu -c \ 'python3 -m pip install --quiet tlcpack-sphinx-addon==0.2.1 && python3 -m pip freeze' > frozen-requirements.txt pip install -r frozen-requirements.txt

3. 生成文档（TVM_TUTORIAL_EXEC_PATTERN=none可跳过教程执行，使构建在大多数环境如 macOS 上可用）：

   export TVM_TUTORIAL_EXEC_PATTERN=none cd docs make html

4. 启动 HTTP 服务并访问 http://localhost:8000：

   cd _build/html && python3 -m http.server

只执行指定的教程

文档构建过程会执行 sphinx-gallery 中的所有教程，在某些机器缺少必要环境时会导致失败。可以通过TVM_TUTORIAL_EXEC_PATTERN设置正则表达式，只执行路径匹配的教程。例如只构建/vta/tutorials下的教程：

python tests/scripts/ci.py docs --tutorial-pattern=/vta/tutorials

只构建某一个具体文件：

# 反斜杠 \ 用于在正则表达式中匹配 . python tests/scripts/ci.py docs --tutorial-pattern=file_name\.py

辅助脚本

• 运行 tests/scripts/task_python_docs.sh 可复现 CI 的 sphinx pre-check 阶段，该脚本跳过教程执行，适合快速检查内容；
• 运行python tests/scripts/ci.py docs --full则执行包含教程运行的完整构建，这需要 GPU CI 环境。

教程排序与 Colab 集成

教程的排序可以通过 docs/conf.py 中的subsection_order与within_subsection_order控制；默认情况下，同一小节内的教程按文件名排序。within_subsection_order中的未列出的文件总是排在已列出文件之后。

所有 TVM 教程都可以通过页面顶部的按钮在 Google Colab 中交互式运行。sphinx-gallery 会为每个教程构建.ipynb文件，由 tvm-bot 自动部署。要确保教程在 Colab 上正确运行，教程中的非 Python 部分（例如依赖安装）应使用 IPython magic 命令前缀，这些命令不会出现在构建出的 HTML 文件中。例如安装 PyTorch：

###################################################################### # To run this tutorial, we must install PyTorch: # # .. code-block:: bash # # %%shell # pip install torch #

在 docs/conf.py 中可以找到配套的底层实现证据：它通过monkey_patch装饰器修改了 sphinx-gallery 的split_code_and_text_blocks、save_rst_example、jupyter_notebook、rst2md等函数，从而注入 "Open in Colab" 按钮、支持include指令，并根据版本（dev/fixed）与是否 CUDA（教程文件中# sphinx_gallery_requires_cuda = True标志）自动选择对应的安装代码块（%%shell+pip install apache-tvm系列）。

仓库中的对应资源速览

为了让读者快速定位相关材料，以下是本文涉及的仓库关键路径：

总结

TVM 的文档体系以 Divio 四类文档模型为骨架，结合用户/开发者指南分流、专题指南与 Getting Started 板块形成了清晰的信息架构；在技术实现上，以 Sphinx 为构建核心，Python 侧采用 numpydoc 格式并由 autodoc 从 docs/reference/api/python 自动生成参考文档，C++ 侧采用 Doxygen 格式，实操型 how-to 则通过 sphinx-gallery 在 gallery 中边执行边生成页面。贡献者在撰写文档时，只需遵循本文所述的分类定位、docstring 格式、交叉引用与图片管理规范，并通过 docs/README.md 中的 Docker 或原生流程本地验证，即可让文档顺利融入 TVM 的在线文档体系。

【免费下载链接】tvmOpen deep learning compiler stack for cpu, gpu and specialized accelerators项目地址: https://gitcode.com/gh_mirrors/tvm7/tvm