Add sphinx_gallery flag for requiring CUDA

Flag tutorials that require cuda

Clarify docstring slightly

Change position of requires_cuda config

Allow other sphinx_gallery flags inside request hook

Fix comments and admonition directives

Fix microTVM install scripts

docs/conf.py

@@ -38,8 +38,8 @@
 from pathlib import Path
 import re
 import sys
+from textwrap import dedent, indent
 from unittest.mock import patch
-import textwrap
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -105,6 +105,21 @@ def decorator(function):
     return decorator
 
 
+CURRENT_FILE_CONF = None
+
+
+@monkey_patch("sphinx_gallery.py_source_parser", "split_code_and_text_blocks")
+def split_code_and_text_blocks(source_file, return_node, real_func):
+    """Monkey-patch split_code_and_text_blocks to expose sphinx-gallery's file-level config.
+
+    It's kinda gross, but we need access to file_conf to detect the requires_cuda flag.
+    """
+    global CURRENT_FILE_CONF
+    file_conf, blocks, node = real_func(source_file, return_node)
+    CURRENT_FILE_CONF = file_conf
+    return (file_conf, blocks, node)
+
+
 # This header replaces the default sphinx-gallery one in sphinx_gallery/gen_rst.py.
 COLAB_HTML_HEADER = """
 .. DO NOT EDIT. THIS FILE WAS AUTOMATICALLY GENERATED BY
@@ -165,7 +180,9 @@ def save_rst_example(example_rst, example_file, time_elapsed, memory_used, galle
 
 
 INCLUDE_DIRECTIVE_RE = re.compile(r"^([ \t]*)\.\. include::\s*(.+)\n", flags=re.M)
-COMMENT_DIRECTIVE_RE = re.compile(r"^\.\.(?: .*)?\n(?:   .*\n)*", flags=re.M)
+COMMENT_DIRECTIVE_RE = re.compile(r"^\.\.(?: .*)?\n(?:(?:  .*)?\n)*", flags=re.M)
+ADMONITION_DIRECTIVE_RE = re.compile(rf"^\.\. admonition:: *(.*)\n((?:(?:  .*)?\n)*)\n", flags=re.M)
+
 
 @monkey_patch("sphinx_gallery.notebook", "rst2md")
 def rst2md(text, gallery_conf, target_dir, heading_levels, real_func):
@@ -174,20 +191,34 @@ def rst2md(text, gallery_conf, target_dir, heading_levels, real_func):
     Currently, only include directives without any parameters are supported. Also, note that in
     reStructuredText any unrecognized explicit markup block is treated as a comment (see
     https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#comments).
+
+    For callouts, we only replace generic "admonition" directives. All others should be replaced by
+    sphinx-gallery's rst2md. Note that the "alert" and "alert-info" tags are support in most IPython
+    notebooks, but they render kinda funky on Colab.
     """
 
     def load_include(match):
         full_path = os.path.join(target_dir, match.group(2))
         with open(full_path) as f:
             lines = f.read()
-        indented = textwrap.indent(lines, match.group(1)) + "\n"
+        indented = indent(lines, match.group(1)) + "\n"
         return indented
 
     text = re.sub(INCLUDE_DIRECTIVE_RE, load_include, text)
-    mostly_converted = real_func(text, gallery_conf, target_dir, heading_levels)
 
-    # All unrecognized directives are treated as comments and removed.
-    return re.sub(COMMENT_DIRECTIVE_RE, "", text)
+    # Replace generic, titled admonitions with indented text. Other admonitions (e.g. .. note::)
+    # will be handled by sphinx-gallery's
+    def rewrite_generic_admonition(match):
+        title, text = match.groups()
+        stripped_text = dedent(text).strip()
+        return f'<div class="alert alert-info"><h4>{title}</h4><p>{stripped_text}</p></div>'
+
+    text = re.sub(ADMONITION_DIRECTIVE_RE, rewrite_generic_admonition, text)
+
+    # Call the real function, and then strip any remaining directives (i.e. comments)
+    text = real_func(text, gallery_conf, target_dir, heading_levels)
+    text = re.sub(COMMENT_DIRECTIVE_RE, "", text)
+    return text
 
 
 INSTALL_TVM_DEV = f"""\
@@ -218,7 +249,6 @@ def load_include(match):
 # source, see see https://tvm.apache.org/docs/install/from_source.html
 pip install apache-tvm-cu113=={version} -f https://tlcpack.ai/wheels"""
 
-CUDA_FUNC_CALL_RE = re.compile(r"cuda\([0-9]*\)", re.IGNORECASE)
 
 @monkey_patch("sphinx_gallery.gen_rst", "jupyter_notebook")
 def jupyter_notebook(script_blocks, gallery_conf, target_dir, real_func):
@@ -228,11 +258,11 @@ def jupyter_notebook(script_blocks, gallery_conf, target_dir, real_func):
     However, how we import TVM depends on if we are using a fixed or dev version, and whether we
     will use the GPU.
 
-    We install a CUDA version of TVM if and only if the tutorial calls "cuda" as a function. It
-    would be cleaner specify this with a config flag, but sphinx-gallery does not support this.
+    Tutorials requiring a CUDA-enabled build of TVM should use the flag:
+    # sphinx_gallery_requires_cuda = True
     """
 
-    requires_cuda = any(CUDA_FUNC_CALL_RE.search(block[1]) for block in script_blocks)
+    requires_cuda = CURRENT_FILE_CONF.get("requires_cuda", False)
     fixed_version = not "dev" in version
 
     if fixed_version and requires_cuda:

gallery/how_to/compile_models/from_keras.py

@@ -36,6 +36,7 @@
 """
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/compile_models/from_mxnet.py

@@ -34,6 +34,7 @@
 """
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/compile_models/from_oneflow.py

@@ -38,6 +38,7 @@
 """
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/deploy_models/deploy_model_on_nano.py

@@ -26,6 +26,7 @@
 """
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/extend_tvm/bring_your_own_datatypes.py

@@ -47,7 +47,7 @@
 
 If you would like to try this with your own datatype library, first bring the library's functions into the process space with ``CDLL``:
 
-.. code-block :: python
+.. code-block:: python
 
     ctypes.CDLL('my-datatype-lib.so', ctypes.RTLD_GLOBAL)
 """

gallery/how_to/optimize_operators/opt_conv_cuda.py

@@ -31,6 +31,7 @@
 """
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/optimize_operators/opt_conv_tensorcore.py

@@ -52,6 +52,7 @@
 # NHWCnc memory layout.The following code defines the convolution algorithm in TVM.
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/tune_with_autoscheduler/tune_conv2d_layer_cuda.py

@@ -38,6 +38,7 @@
 """
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/tune_with_autotvm/tune_conv2d_cuda.py

@@ -49,6 +49,7 @@
 # Now return to python code. Import packages.
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/tune_with_autotvm/tune_relay_cuda.py

@@ -60,6 +60,7 @@
 # Now return to python code. Import packages.
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/work_with_microtvm/install_cmsis.rst

@@ -6,9 +6,9 @@
     "License"); you may not use this file except in compliance
     with the License.  You may obtain a copy of the License at
 
-..    http://www.apache.org/licenses/LICENSE-2.0
+      http://www.apache.org/licenses/LICENSE-2.0
 
-..  Unless required by applicable law or agreed to in writing,
+    Unless required by applicable law or agreed to in writing,
     software distributed under the License is distributed on an
     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied.  See the License for the

gallery/how_to/work_with_microtvm/install_dependencies.rst

@@ -6,9 +6,9 @@
     "License"); you may not use this file except in compliance
     with the License.  You may obtain a copy of the License at
 
-..    http://www.apache.org/licenses/LICENSE-2.0
+      http://www.apache.org/licenses/LICENSE-2.0
 
-..  Unless required by applicable law or agreed to in writing,
+    Unless required by applicable law or agreed to in writing,
     software distributed under the License is distributed on an
     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied.  See the License for the
@@ -23,8 +23,11 @@
 Install microTVM Python dependencies
 ------------------------------------
 
+TVM does not include a package for Python serial communication, so
+we must install one before using microTVM. We will also need TFLite
+to load models.
+
     .. code-block:: bash
 
         %%shell
-        wget https://github.com/guberti/tvm/raw/hackathon/tutorials/apps/microtvm/requirements.txt
-        pip install -r requirements.txt
+        pip install pyserial==3.5 tflite==2.1

gallery/how_to/work_with_microtvm/install_zephyr.rst

@@ -6,9 +6,9 @@
     "License"); you may not use this file except in compliance
     with the License.  You may obtain a copy of the License at
 
-..    http://www.apache.org/licenses/LICENSE-2.0
+      http://www.apache.org/licenses/LICENSE-2.0
 
-..  Unless required by applicable law or agreed to in writing,
+    Unless required by applicable law or agreed to in writing,
     software distributed under the License is distributed on an
     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied.  See the License for the
@@ -46,7 +46,7 @@ Install Zephyr
         wget --no-verbose -O $ZEPHYR_SDK_FILE \
             https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZEPHYR_SDK_VERSION}/zephyr-sdk-${ZEPHYR_SDK_VERSION}-linux-x86_64-setup.run
         chmod +x $ZEPHYR_SDK_FILE
-        "$ZEPHYR_SDK_FILE" -- -d /content/zephyr-sdk
+        "$ZEPHYR_SDK_FILE" -- -d /content/zephyr-sdk --quiet
 
         # Install python dependencies
         python3 -m pip install -r "${ZEPHYR_BASE}/scripts/requirements.txt"

gallery/how_to/work_with_pytorch/using_optimized_torch.py

@@ -32,6 +32,7 @@
 """
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/work_with_relay/using_relay_viz.py

@@ -32,6 +32,13 @@
 Here we use a renderer rendering graph in the text-form.
 It is a lightweight, AST-like visualizer, inspired by `clang ast-dump <https://clang.llvm.org/docs/IntroductionToTheClangAST.html>`_.
 We will introduce how to implement customized parsers and renderers through interface classes.
+To install dependencies, run:
+
+.. code-block:: bash
+
+    %%shell
+    pip install graphviz
+
 
 For more details, please refer to :py:mod:`tvm.contrib.relay_viz`.
 """

gallery/how_to/work_with_schedules/reduction.py

@@ -29,6 +29,7 @@
 
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/how_to/work_with_schedules/scan.py

@@ -26,6 +26,7 @@
 
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/tutorial/intro_topi.py

@@ -27,6 +27,7 @@
 """
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/tutorial/relay_quick_start.py

@@ -27,6 +27,7 @@
 """
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)

gallery/tutorial/tensor_ir_blitz_course.py

@@ -30,6 +30,7 @@
 """
 
 # sphinx_gallery_start_ignore
+# sphinx_gallery_requires_cuda = True
 from tvm import testing
 
 testing.utils.install_request_hook(depth=3)