Fix comments and admonition directives

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
@@ -180,7 +180,8 @@ 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")
@@ -190,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"""\

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/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

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