TVM 准备

TVM 的文档托管在 https://tvm.apache.org/docs

本地构建

使用 Docker（推荐）

1. Build TVM and the docs inside the tlcpack/ci-gpu image using the ci.py script.

   # If this runs into errors, try cleaning your 'build' directory
   python tests/scripts/ci.py docs
   
   # See other doc building options
   python tests/scripts/ci.py docs --help
   

2. 服务文档 docs 并可在浏览器 http://localhost:8000 访问

   # Run an HTTP server you can visit to view the docs in your browser
   python tests/scripts/ci.py serve-docs
   

原生应用

1. 首先在 repo 根目录下 建立 TVM

2. 安装依赖

   # Pillow on Ubuntu may require libjpeg-dev from apt
   ./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. 生成 docs

   # TVM_TUTORIAL_EXEC_PATTERN=none skips the tutorial execution to the build
   # work on most environments (e.g. MacOS).
   export TVM_TUTORIAL_EXEC_PATTERN=none
   
   cd docs
   make html
   

4. 运行 HTTP 服务并可以在浏览器 http://localhost:8000 访问

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

仅执行指定的教程

文档构建过程将执行 sphinx 库中的所有教程。在某些情况下，如果某些机器没有必要的环境，这将导致失败。你可以设置 TVM_TUTORIAL_EXEC_PATTERN，只执行符合正则表达式的路径。

例如，要想只在 /vta/tutorials 下构建教程，运行

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

要想只建立特定的文件，请执行

# The slash \ is used to get . in regular expression
python tests/scripts/ci.py docs --tutorial-pattern=file_name\.py

辅助脚本

你可以运行以下脚本来重现 CI sphinx 的预检查阶段。这个脚本跳过了教程的执行，对快速检查内容很有用。

tests/scripts/task_python_docs.sh

下面的脚本运行完整的构建，包括教程的执行。你将需要一个 GPU CI 环境。

python tests/scripts/ci.py docs --full

定义教程的顺序

你可以在 conf.py 中用 subsection_order 和 within_subsection_order 来定义教程的顺序。默认情况下，一个小节内的教程是按文件名排序的。

集成 Google Colab

所有 TVM 教程都可以通过点击页面顶部的按钮在 Google Colab 中打开和交互式使用。为此，sphinx-gallery 会从每个教程构建 .ipynb 文件，这些文件会自动部署到 apache/tvm-site 仓库的 asf-site 分支上，这是由 @tvm-bot 完成的。

为了确保你的教程在 Colab 上正确运行，教程中的任何非 Python 部分（例如依赖项安装）都应该使用 IPython 魔术命令进行前缀。这些内容不会被包含在构建的 HTML 文件中。例如，要在教程中安装 Pytorch，可以添加 ReStructured Text 块，如下所示：

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

交互式 Bash 脚本

在 IPython 堆栈中，应该使用 %%bash 魔术命令来运行 shell 命令。然而，这个命令并不提供实时输出 - 教程的用户将不会看到任何输出，直到整个单元格运行完毕。当运行需要几分钟（例如安装依赖项）的命令时，这很烦人。

幸运的是，Google Colab有 %%shell 魔术命令，它可以执行与 %%bash 相同的操作，但实时输出结果。该命令是 Colab 特有的，其源代码代码可公开获得。因此，在编写 TVM 教程时，应该使用 %%shell 命令代替 %%bash 命令。