This folder contains the source of TVM's documentation, hosted at https://tvm.apache.org/docs
Run these commands from the repository root. The Docker image aliases select this checkout's CI images; their first download can take some time.
Build the FFI, TIRx, and TVM wheels in dependency order and run the CPU C++ tests, using the same commands as CI:
docker/bash.sh ci_cpu bash -euo pipefail -c ' source ./tests/scripts/task_install_build_dependencies.sh ./tests/scripts/task_build_cpu.sh sccache --show-stats '
Build the Python documentation without executing tutorials. Install the additional CPU documentation dependencies in the same container as the build:
docker/bash.sh --env IS_LOCAL=1 \ --env PYTHON_DOCS_ONLY=1 --env TVM_TUTORIAL_EXEC_PATTERN=none \ ci_cpu bash -euo pipefail -c ' tests/scripts/task_install_docs_dependencies.sh source tests/scripts/test_task_install_dist_wheels.sh tests/scripts/task_python_docs.sh '
The sourced helper installs the wheels from dist/ and sets PYTHONPATH for the docs script. Rebuild the wheels after changing TVM code; documentation-only edits can reuse them.
Serve the generated docs and visit http://localhost:8000 in your browser:
python3 -m http.server --directory _docs
For the full documentation build, including GPU tutorials and non-Python APIs, see Helper Scripts below.
Build TVM first in the repo root folder, then make it importable:
export TVM_HOME=/path-to-tvm export TVM_LIBRARY_PATH=$TVM_HOME/build pip install --target=$TVM_HOME/python $TVM_HOME/3rdparty/tvm-tirx/3rdparty/tvm-ffi export PYTHONPATH="$TVM_HOME/3rdparty/tvm-tirx/python:$TVM_HOME/python:${PYTHONPATH:-}" export TVM_TIRX_LIBRARY_PATH="${TVM_HOME}/build/lib"
docs/conf.py unconditionally imports tvm at startup, so the build will fail immediately if TVM is not importable.
Install dependencies
# Pillow on Ubuntu may require libjpeg-dev from apt ./docker/bash.sh ci_gpu -c \ 'python3 -m pip install --quiet sphinx-book-theme==1.1.4 && python3 -m pip freeze' > frozen-requirements.txt pip install -r frozen-requirements.txt
Generate the 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
Run an HTTP server and visit http://localhost:8000 in your browser
cd _build/html && python3 -m http.server
The document build process will execute all the tutorials in the sphinx gallery. This will cause failure in some cases when certain machines do not have necessary environment. You can set TVM_TUTORIAL_EXEC_PATTERN to only execute the path that matches the regular expression pattern.
After building GPU wheels as shown below, execute only tutorials under /get_started/tutorials with:
docker/bash.sh --env IS_LOCAL=1 \ --env PYTHON_DOCS_ONLY=1 --env TVM_TUTORIAL_EXEC_PATTERN=/get_started/tutorials \ ci_gpu bash -euo pipefail -c ' source tests/scripts/test_task_install_dist_wheels.sh tests/scripts/task_python_docs.sh '
To execute only one file, use a regular expression matching its name. Quote the pattern so the shell preserves the backslash that escapes the dot:
docker/bash.sh --env IS_LOCAL=1 \ --env PYTHON_DOCS_ONLY=1 --env 'TVM_TUTORIAL_EXEC_PATTERN=file_name\.py' \ ci_gpu bash -euo pipefail -c ' source tests/scripts/test_task_install_dist_wheels.sh tests/scripts/task_python_docs.sh '
tests/scripts/task_python_docs.sh mirrors the CI docs pipeline. It runs a Sphinx warning pre-check when IS_LOCAL=0, then builds the documentation with make htmldepoly. IS_LOCAL=1 skips the pre-check; the final build still checks warnings. PYTHON_DOCS_ONLY=1 skips the C++, Java, and TypeScript API docs for local builds.
To run the full build, including tutorial execution and all API docs, use a host with an NVIDIA GPU and Docker GPU support:
docker/bash.sh --no-gpu ci_gpu bash -euo pipefail -c ' source ./tests/scripts/task_install_build_dependencies.sh ./tests/scripts/task_build_gpu.sh sccache --show-stats ' docker/bash.sh --env IS_LOCAL=1 \ --env PYTHON_DOCS_ONLY=0 --env TVM_TUTORIAL_EXEC_PATTERN=.py \ ci_gpu bash -euo pipefail -c ' source tests/scripts/test_task_install_dist_wheels.sh tests/scripts/task_python_docs.sh ' python3 -m http.server --directory _docs
Native builds use build/ and wheels use dist/. Clean these directories and run the matching platform build when switching between CPU and GPU documentation builds.
You can define the order of tutorials with subsection_order and within_subsection_order in conf.py. By default, the tutorials within one subsection are sorted by filename.
All the TVM tutorials can be opened and used interactively in Google Colab by clicking the button at the top of the page. To do this, sphinx-gallery builds .ipynb files from each tutorial, which are automatically deployed to the apache/tvm-site repo's asf-site branch by @tvm-bot.
To make sure your tutorial runs correctly on Colab, any non-Python parts of the tutorial (e.g. dependency installations) should be prefixed by an IPython magic command. These will not be included in the built HTML file. For example, to install Pytorch in your tutorial, add a ReStructured Text block like the following:
###################################################################### # To run this tutorial, we must install PyTorch: # # .. code-block:: bash # # %%shell # pip install torch #
In stock IPython, the %%bash magic command should be used to run shell commands. However, this command does not give real-time output - the tutorial's user will not see any output until the entire cell finishes running. When running commands that take several minutes (e.g. installing dependencies), this is annoying.
Luckily, Google Colab has the %%shell magic command that does the same thing as %%bash, but gives output in real time. This command is specific to Colab, and its source code is public. Thus, %%shell should be used instead of %%bash when writing TVM tutorials.