DOC: Custom Sphinx extension to invoke Jupytext

doc/source/conf.py

@@ -23,6 +23,27 @@
 except TypeError:
     pass
 
+from sphinx.application import Sphinx
+
+
+def convert_md_to_ipynb(app: Sphinx, *args, **kwargs):
+    import subprocess
+    import sys
+    print("Converting Markdown files to IPyNB...")
+    print("This may take a while.")
+    subprocess.check_call(
+        [
+            sys.executable,
+            "-m",
+            "jupytext",
+            "--to",
+            "ipynb",
+            "doc/source/regression/*.md",
+        ]
+    )
+
+def setup(app):
+    app.connect("config-inited", convert_md_to_ipynb)
 
 # 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
@@ -53,7 +74,11 @@
 templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'myst-nb',
+    'ipynb': None,  # do not parse IPyNB files
+}
 
 # The encoding of source files.
 source_encoding = 'utf-8'
@@ -276,7 +301,10 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['substitutions.rst', ]
+exclude_patterns = [
+    'substitutions.rst',
+    'regression/*.ipynb'  # exclude IPyNB files from the build
+]
 
 # numpydoc_show_class_members = False
 numpydoc_class_members_toctree = False