Start conversion to markdown

Converts a few selected pages to markdown, and adds requirements and configuration needed
for the conversion.

Author: melissawm

conf.py

@@ -9,7 +9,12 @@
 # General configuration
 # ---------------------
 
-exclude_patterns = ["README.rst"]
+exclude_patterns = [
+    "README.rst",
+    ".jupyter_cache",
+    "jupyter_execute",
+    "pyximages/README.md",
+]
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -23,6 +28,7 @@
     "sphinx.ext.extlinks",
     "sphinx_gallery.gen_gallery",
     "sphinx_copybutton",
+    "myst_nb",
 ]
 
 # See https://sphinx-copybutton.readthedocs.io/en/latest/use.html#automatic-exclusion-of-prompts-from-the-copies
@@ -72,7 +78,7 @@
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # General information about the project.
 project = "Scientific Python Lectures"
@@ -91,6 +97,18 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
+# Enable executable .md files support
+myst_enable_extensions = [
+    'colon_fence',
+    'dollarmath',
+    'substitution',
+    'tasklist',
+    'attrs_inline',
+    'linkify',
+]
+
+nb_output_stderr = 'show'
+
 # Monkey-patch sphinx to set the lineseparator option of pygment, to
 # have indented line wrapping
 
@@ -288,6 +306,8 @@ def add_per_page_js(app, pagename, templatename, context, doctree):
 
 
 def setup(app):
+    # Do not execute .ipynb files generated by the gallery
+    app.registry.source_suffix.pop(".ipynb", None)
     app.add_js_file("https://code.jquery.com/jquery-3.7.0.min.js")
     app.add_js_file("scroll_highlight_toc.js")