From d96c88d2ee0b553f13d2220cde0bb60564c9ac68 Mon Sep 17 00:00:00 2001 From: Gavin Uberti Date: Thu, 29 Dec 2022 11:56:15 -0800 Subject: [PATCH] Fix comments and admonition directives --- docs/conf.py | 27 ++++++++++++++----- .../extend_tvm/bring_your_own_datatypes.py | 2 +- .../work_with_microtvm/install_cmsis.rst | 4 +-- .../install_dependencies.rst | 4 +-- .../work_with_microtvm/install_zephyr.rst | 4 +-- 5 files changed, 28 insertions(+), 13 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 579c9be4addd8..357df8cef12c7 100644 --- a/docs/conf.py +++ b/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'

{title}

{stripped_text}

' + + 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"""\ diff --git a/gallery/how_to/extend_tvm/bring_your_own_datatypes.py b/gallery/how_to/extend_tvm/bring_your_own_datatypes.py index 479269a224a3f..bbd207dbac8bc 100644 --- a/gallery/how_to/extend_tvm/bring_your_own_datatypes.py +++ b/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) """ diff --git a/gallery/how_to/work_with_microtvm/install_cmsis.rst b/gallery/how_to/work_with_microtvm/install_cmsis.rst index f1c0cd1b39ab3..2f1d2fb1189a5 100644 --- a/gallery/how_to/work_with_microtvm/install_cmsis.rst +++ b/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 diff --git a/gallery/how_to/work_with_microtvm/install_dependencies.rst b/gallery/how_to/work_with_microtvm/install_dependencies.rst index 880b5ae625fb2..925323d269387 100644 --- a/gallery/how_to/work_with_microtvm/install_dependencies.rst +++ b/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 diff --git a/gallery/how_to/work_with_microtvm/install_zephyr.rst b/gallery/how_to/work_with_microtvm/install_zephyr.rst index 489ece9745441..14558941d1155 100644 --- a/gallery/how_to/work_with_microtvm/install_zephyr.rst +++ b/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