TVM 准备

TVM 准备#

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

本地构建#

使用 Docker（推荐）#

在 Docker 镜像 tlcpack/ci-gpu 内构建 TVM 及其文档

# 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

服务文档 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

原生应用#

安装依赖

# 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

生成 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

运行 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 命令。