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

Apache TVM 文档写作指南基于 Divio 体系的四类文档组织与 Sphinx 构建实践【免费下载链接】tvmOpen deep learning compiler stack for cpu, gpu and specialized accelerators项目地址: https://gitcode.com/gh_mirrors/tvm7/tvmApache 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, arg33): 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-ToTVM 使用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原生构建方式先在仓库根目录构建 TVM安装依赖Ubuntu 上 Pillow 可能需要 apt 安装 libjpeg-dev./docker/bash.sh ci_gpu -c \ python3 -m pip install --quiet tlcpack-sphinx-addon0.2.1 python3 -m pip freeze frozen-requirements.txt pip install -r frozen-requirements.txt生成文档TVM_TUTORIAL_EXEC_PATTERNnone可跳过教程执行使构建在大多数环境如 macOS 上可用export TVM_TUTORIAL_EXEC_PATTERNnone cd docs make html启动 HTTP 服务并访问 http://localhost:8000cd _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-patternfile_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标志自动选择对应的安装代码块%%shellpip install apache-tvm系列。仓库中的对应资源速览为了让读者快速定位相关材料以下是本文涉及的仓库关键路径用途路径文档构建配置Sphinx 扩展、gallery 映射、排序、Colab 集成docs/conf.py本地构建文档的完整说明docs/README.mdPython API 参考autodoc 规则目录docs/reference/api/pythonHow-To 文档索引docs/how_to/index.rst架构指南docs/arch专题指南microTVM、VTAdocs/topic/microtvm、docs/topic/vtasphinx-gallery 教程源码gallery、vta/tutorialsC 文档构建配置docs/DoxyfileCI 文档构建入口tests/scripts/ci.py总结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考