Use ci.py explicitly in docs building instructions

This adds `ci.py` to the docs to make it more clear how to easily build the docs locally. This also re-arranges CI following the merging of all CI steps to run concurrently since there's no need to run the Sphinx precheck during GPU unit tests. This still preserves it though in the docs step as a way to quickly bail out if there are formatting errors so the full tutorials don't get built.

Author: driazati

Jenkinsfile

@@ -388,10 +388,6 @@ stage('Test') {
             unpack_lib('gpu', tvm_multilib)
             timeout(time: max_time, unit: 'MINUTES') {
               ci_setup(ci_gpu)
-              sh (
-                script: "${docker_run} ${ci_gpu} ./tests/scripts/task_sphinx_precheck.sh",
-                label: 'Check Sphinx warnings in docs',
-              )
               sh (
                 script: "${docker_run} ${ci_gpu} ./tests/scripts/task_java_unittest.sh",
                 label: 'Run Java unit tests',

docs/README.md

@@ -16,52 +16,61 @@
 <!--- under the License. -->
 
 # TVM Documentation
+
 This folder contains the source of TVM's documentation, hosted at https://tvm.apache.org/docs
 
 ## Build Locally
 
-See also the instructions below to run a specific tutorial. Note that some of the tutorials need GPU support. Once build, either of these can be served using Python's build in HTTP server:
+### With Docker (recommended)
 
-```bash
-# Run this and then visit http://localhost:8000 in your browser
-cd docs/_build/html && python3 -m http.server
-```
+1. Build TVM and the docs inside the [tlcpack/ci-gpu image](https://hub.docker.com/r/tlcpack/ci-gpu) using the [`ci.py`](../tests/scripts/ci.py) script.
 
-### With Docker (recommended)
+   ```bash
+   # If this runs into errors, try cleaning your 'build' directory
+   python tests/scripts/ci.py docs
 
-1. Build TVM and the docs inside the [tlcpack/ci-gpu image](https://hub.docker.com/r/tlcpack/ci-gpu)
+   # See other doc building options
+   python tests/scripts/ci.py docs --help
+   ```
 
-    ```bash
-    # If this runs into errors, try cleaning your 'build' directory
-    make docs
-    ```
+2. Serve the docs and visit http://localhost:8000 in your browser
 
+   ```bash
+   # Run an HTTP server you can visit to view the docs in your browser
+   python tests/scripts/ci.py serve-docs
+   ```
 
 ### Native
 
 1. [Build TVM](https://tvm.apache.org/docs/install/from_source.html) first in the repo root folder
 2. Install dependencies
 
-    ```bash
-    # Pillow on Ubuntu may require libjpeg-dev from apt
-    docker run tlcpack/ci-gpu:v0.78 bash -c \
-        'python3 -m pip install --quiet tlcpack-sphinx-addon==0.2.1 synr==0.5.0 && python3 -m pip freeze' > frozen-requirements.txt
+   ```bash
+   # Pillow on Ubuntu may require libjpeg-dev from apt
+   docker run tlcpack/ci-gpu:v0.78 bash -c \
+       'python3 -m pip install --quiet tlcpack-sphinx-addon==0.2.1 synr==0.5.0 && python3 -m pip freeze' > frozen-requirements.txt
 
-    pip install -r frozen-requirements.txt
-    ```
+   pip install -r frozen-requirements.txt
+   ```
 
 3. Generate the docs
 
-    ```bash
-    # 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
+   ```bash
+   # 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
+
+   make html
+   ```
 
-    make html
-    ```
+4. Run an HTTP server and visit http://localhost:8000 in your browser
 
+   ```bash
+   cd docs/_build/html && python3 -m http.server
+   ```
 
 ## Only Execute Specified Tutorials
+
 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
@@ -70,14 +79,14 @@ the path that matches the regular expression pattern.
 For example, to only build tutorials under `/vta/tutorials`, run
 
 ```bash
-TVM_TUTORIAL_EXEC_PATTERN=/vta/tutorials make html
+python tests/scripts/ci.py docs --tutorials=/vta/tutorials
 ```
 
 To only build one specific file, do
 
 ```bash
 # The slash \ is used to get . in regular expression
-TVM_TUTORIAL_EXEC_PATTERN=file_name\.py make html
+python tests/scripts/ci.py docs --tutorials=file_name\.py
 ```
 
 ## Helper Scripts
@@ -86,7 +95,7 @@ You can run the following script to reproduce the CI sphinx pre-check stage.
 This script skips the tutorial executions and is useful to quickly check the content.
 
 ```bash
-./tests/scripts/task_sphinx_precheck.sh
+python tests/scripts/ci.py docs --precheck
 ```
 
 The following script runs the full build which includes tutorial executions.
@@ -97,5 +106,7 @@ python tests/scripts/ci.py --precheck --full
 ```
 
 ## Define the Order of Tutorials
-You can define the order of tutorials with `conf.py::subsection_order` and `conf.py::within_subsection_order`.
-By default, the tutorials within one subsection is sorted by filename.
+
+You can define the order of tutorials with `subsection_order` and
+`within_subsection_order` in [`conf.py`](conf.py).
+By default, the tutorials within one subsection are sorted by filename.

tests/scripts/ci.py

@@ -174,13 +174,11 @@ def docker(name: str, image: str, scripts: List[str], env: Dict[str, str]):
 def docs(
     tutorial_pattern: Optional[str] = None,
     full: bool = False,
-    precheck: bool = False,
     cpu: bool = False,
 ) -> None:
     """
     Build the documentation from gallery/ and docs/. By default this builds only
-    the Python docs. If you are on a CPU machine, you can skip the tutorials
-    and build the docs with the '--precheck --cpu' options.
+    the Python docs.
 
     arguments:
     full -- Build all language docs, not just Python
@@ -233,9 +231,7 @@ def docs(
         config,
         f"./tests/scripts/task_build.sh build -j{NPROC}",
         "./tests/scripts/task_ci_setup.sh",
-        "./tests/scripts/task_sphinx_precheck.sh"
-        if precheck
-        else "./tests/scripts/task_python_docs.sh",
+        "./tests/scripts/task_python_docs.sh",
     ]
 
     if tutorial_pattern is None:

tests/scripts/task_python_docs.sh

@@ -16,15 +16,13 @@
 # specific language governing permissions and limitations
 # under the License.
 
-set -e
-set -u
-set -o pipefail
+set -euo pipefail
 
 source tests/scripts/setup-pytest-env.sh
 
 # to avoid CI CPU thread throttling.
 export TVM_BIND_THREADS=0
-export OMP_NUM_THREADS=4
+export OMP_NUM_THREADS=1
 IS_LOCAL=${IS_LOCAL:-0}
 PYTHON_DOCS_ONLY=${PYTHON_DOCS_ONLY:-0}
 
@@ -34,14 +32,75 @@ cleanup()
 }
 trap cleanup 0
 
-# cleanup old states
-rm -rf docs/_build
-rm -rf docs/_staging
-mkdir -p docs/_build/html
-mkdir -p docs/_staging/html
-rm -rf docs/gen_modules
-rm -rf docs/doxygen
+clean_files() {
+    # cleanup old states
+    rm -rf docs/_build
+    rm -rf docs/_staging
+    mkdir -p docs/_build/html
+    mkdir -p docs/_staging/html
+    rm -rf docs/gen_modules
+    rm -rf docs/doxygen
+    find . -type f -path "*.pyc" | xargs rm -f
+}
+
+sphinx_precheck() {
+    clean_files
+    echo "PreCheck sphinx doc generation WARNINGS.."
+    make cython3
+
+    pushd docs
+    make clean
+    TVM_TUTORIAL_EXEC_PATTERN=none make html 2>&1 | tee /tmp/$$.log.txt
+    check_sphinx_warnings
+    popd
+}
+
+
+function join_by { local IFS="$1"; shift; echo "$*"; }
+
+IGNORED_WARNINGS=(
+    '__mro__'
+    'UserWarning'
+    'FutureWarning'
+    'tensorflow'
+    'Keras'
+    'pytorch'
+    'TensorFlow'
+    'coremltools'
+    '403'
+    'git describe'
+    'scikit-learn version'
+    'doing serial write'
+    'gen_gallery extension is not safe for parallel'
+    'strategy:conv2d NHWC layout is not optimized for x86 with autotvm.'
+    'strategy:depthwise_conv2d NHWC layout is not optimized for x86 with autotvm.'
+    'autotvm:Cannot find config for target=llvm -keys=cpu -link-params=0'
+    'autotvm:One or more operators have not been tuned. Please tune your model for better performance. Use DEBUG logging level to see more details.'
+)
+
+JOINED_WARNINGS=$(join_by '|' "${IGNORED_WARNINGS[@]}")
+
+check_sphinx_warnings() {
+    grep -v -E "$JOINED_WARNINGS" < /tmp/$$.log.txt > /tmp/$$.logclean.txt || true
+    if grep --quiet -E "WARN" < /tmp/$$.logclean.txt; then
+        echo "Lines with 'WARNING' found in the log, please fix them:"
+        grep -E "WARN" < /tmp/$$.logclean.txt
+        echo "You can reproduce locally by running 'python tests/scripts/ci.py docs'"
+        exit 1
+    fi
+    echo "No WARNINGS to be fixed."
+}
 
+# run precheck step first to fast-fail if there are problems with the docs
+if [ "$IS_LOCAL" != "1" ]; then
+    echo "Running precheck"
+    sphinx_precheck
+else
+    echo "Skipping precheck"
+fi
+
+
+clean_files
 # prepare auto scheduler tutorials
 rm -rf gallery/how_to/tune_with_auto_scheduler/*.json
 rm -rf gallery/tutorial/*.json
@@ -55,11 +114,14 @@ find . -type f -path "*.pyc" | xargs rm -f
 make cython3
 
 cd docs
-PYTHONPATH=`pwd`/../python make html SPHINXOPTS='-j auto' |& tee /tmp/$$.log.txt
+PYTHONPATH=$(pwd)/../python make html SPHINXOPTS='-j auto' |& tee /tmp/$$.log.txt
 if grep -E "failed to execute|Segmentation fault" < /tmp/$$.log.txt; then
     echo "Some of sphinx-gallery item example failed to execute."
     exit 1
 fi
+
+check_sphinx_warnings
+
 cd ..
 
 if [ "$IS_LOCAL" == "1" ] && [ "$PYTHON_DOCS_ONLY" == "1" ]; then

tests/scripts/task_sphinx_precheck.sh

@@ -16,36 +16,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
-# Precheck if sphinx docs build can fail.
-set -e
-set -u
-set -o pipefail
-
-cleanup()
-{
-    rm -rf /tmp/$$.*
-}
-trap cleanup 0
-
-# cleanup cache
-rm -rf docs/_staging
-rm -rf docs/_build
-find . -type f -path "*.pyc" | xargs rm -f
-make cython3
-
-echo "PreCheck sphinx doc generation WARNINGS.."
-cd docs
-make clean
-TVM_TUTORIAL_EXEC_PATTERN=none make html 2>&1 | tee /tmp/$$.log.txt
-
-grep -v -E "__mro__|UserWarning|FutureWarning|tensorflow|Keras|pytorch|TensorFlow|coremltools|403|git describe|scikit-learn version" < /tmp/$$.log.txt > /tmp/$$.logclean.txt || true
-echo "---------Sphinx Log----------"
-cat /tmp/$$.logclean.txt
-echo "-----------------------------"
-if grep --quiet -E "WARN" < /tmp/$$.logclean.txt; then
-    echo "WARNING found in the log, please fix them."
-    grep -E "WARN" < /tmp/$$.logclean.txt
-    echo "You can reproduce locally by running ./tests/scripts/task_sphinx_precheck.sh"
-    exit 1
-fi
-echo "No WARNINGS to be fixed."
+# Intentionally do nothing, see https://github.com/apache/tvm/pull/9971. This
+# file cannot be deleted from the Jenkinsfile and deleted from the repo in the
+# same PR (since it wouldn't be able to pass CI). Once that PR is merged, this
+# file can be safely deleted.