DOC: Add interactive notebooks to pages in the "Usage Examples" section

.gitignore

@@ -24,6 +24,8 @@ pip-log.txt
 doc/_build/
 doc/build/
 .jupyterlite.doit.db
+/doc/jupyter_execute/
+doc/source/regression/*.ipynb
 
 # Editors
 .idea

doc/source/_static/myst-nb.css

@@ -0,0 +1,82 @@
+/* MyST-NB
+
+This stylesheet targets elements output by MyST-NB that represent notebook
+cells.
+
+In some cases these rules override MyST-NB. In some cases they override PyData
+Sphinx Theme or Sphinx. And in some cases they do not override existing styling
+but add new styling. */
+
+/* Set up a few variables for this stylesheet */
+.cell,
+.pywt-handcoded-cell-output {
+  --pywt-cell-input-border-left-width: .2rem;
+
+  /* This matches the padding applied to <pre> elements by PyData Sphinx Theme */
+  --pywt-code-block-padding: 1rem;
+
+  /* override mystnb */
+  --mystnb-source-border-radius: .25rem; /* match PyData Sphinx Theme */
+}
+
+.cell .cell_input::before {
+  content: "In";
+  border-bottom: var(--mystnb-source-border-width) solid var(--pst-color-border);
+  font-weight: var(--pst-font-weight-caption);
+
+  /* Left-aligns the text in this box and the one that follows it */
+  padding-left: var(--pywt-code-block-padding);
+}
+
+/* Cannot use `.cell .cell_input` selector because the stylesheet from MyST-NB
+   uses `div.cell div.cell_input` and we want to override those rules */
+div.cell div.cell_input {
+  background-color: inherit;
+  border-color: var(--pst-color-border);
+  border-left-width: var(--pywt-cell-input-border-left-width);
+  background-clip: padding-box;
+  overflow: hidden;
+}
+
+.cell .cell_output,
+.pywt-handcoded-cell-output {
+  border: var(--mystnb-source-border-width) solid var(--pst-color-surface);
+  border-radius: var(--mystnb-source-border-radius);
+  background-clip: padding-box;
+  overflow: hidden;
+}
+
+.cell .cell_output::before,
+.pywt-handcoded-cell-output::before {
+  content: "Out";
+  display: block;
+  font-weight: var(--pst-font-weight-caption);
+
+  /* Left-aligns the text in this box and the one that follows it */
+  padding-left: var(--pywt-code-block-padding);
+}
+
+.cell .cell_output .output {
+  background-color: inherit;
+  border: none;
+  margin-top: 0;
+}
+
+.cell .cell_output,
+/* must prefix the following selector with `div.` to override Sphinx margin rule on div[class*=highlight-] */
+div.pywt-handcoded-cell-output {
+  /* Left-align the text in the output with the text in the input */
+  margin-left: calc(var(--pywt-cell-input-border-left-width) - var(--mystnb-source-border-width));
+}
+
+.cell .cell_output .output,
+.cell .cell_input pre,
+.cell .cell_output pre,
+.pywt-handcoded-cell-output .highlight,
+.pywt-handcoded-cell-output pre {
+  border-radius: 0;
+}
+
+.pywt-handcoded-cell-output pre {
+  border: none; /* MyST-NB sets border to none for <pre> tags inside div.cell */
+}

doc/source/_static/pywavelets.css

@@ -1,27 +1,37 @@
 /* Custom CSS rules for the interactive documentation button */
 
 .try_examples_button {
-    color: white;
-    background-color: #0054a6;
-    border: none;
-    padding: 5px 10px;
-    border-radius: 10px;
-    margin-bottom: 5px;
-    box-shadow: 0 2px 5px rgba(108,108,108,0.2);
-    font-weight: bold;
-    font-size: small;
+  color: white;
+  background-color: #0054a6;
+  border: none;
+  padding: 5px 10px;
+  border-radius: 10px;
+  margin-bottom: 5px;
+  box-shadow: 0 2px 5px rgba(108,108,108,0.2);
+  font-weight: bold;
+  font-size: small;
 }
 
 .try_examples_button:hover {
-background-color: #0066cc;
-transform: scale(1.02);
-box-shadow: 0 2px 5px rgba(0, 0, 0, 0.2);
-cursor: pointer;
+  background-color: #0066cc;
+  transform: scale(1.02);
+  box-shadow: 0 2px 5px rgba(0, 0, 0, 0.2);
+  cursor: pointer;
 }
 
 .try_examples_button_container {
-    display: flex;
-    justify-content: flex-start;
-    gap: 10px;
-    margin-bottom: 20px;
+  display: flex;
+  justify-content: flex-start;
+  gap: 10px;
+  margin-bottom: 20px;
+}
+
+/*
+Admonitions on this site are styled with some top margin. This makes sense when
+the admonition appears within the flow of the article. But when it is the very
+first child of an article, its top margin gets added to the article's top
+padding, resulting in too much whitespace.
+*/
+.admonition.pywt-margin-top-0 {
+  margin-top: 0;
 }

doc/source/conf.py

@@ -11,9 +11,10 @@
 # serve to show the default.
 
 import datetime
-import importlib.metadata
+import os
+import re
+from pathlib import Path
 
-import jinja2.filters
 import numpy as np
 
 import pywt
@@ -25,6 +26,76 @@
 except TypeError:
     pass
 
+from sphinx.application import Sphinx
+
+HERE = Path(__file__).parent
+
+
+def preprocess_notebooks(app: Sphinx, *args, **kwargs):
+    """Preprocess Markdown notebooks to convert them to IPyNB format."""
+
+    import jupytext
+    import nbformat
+
+    print("Converting Markdown files to IPyNB...")
+    for path in (HERE / "regression").glob("*.md"):
+        if any(path.match(pattern) for pattern in exclude_patterns):
+            continue
+        nb = jupytext.read(str(path))
+
+        # In .md to .ipynb conversion, do not include any cells that have the
+        # jupyterlite_sphinx_strip tag
+        nb.cells = [
+            cell for cell in nb.cells if "jupyterlite_sphinx_strip" not in cell.metadata.get("tags", [])
+        ]
+
+        ipynb_path = path.with_suffix(".ipynb")
+        with open(ipynb_path, "w") as f:
+            nbformat.write(nb, f)
+            print(f"Converted {path} to {ipynb_path}")
+
+
+# Should match {{ parent_docname }} or {{parent_docname}}
+parent_docname_substitution_re = re.compile(r"{{\s*parent_docname\s*}}")
+
+def sub_parent_docname_in_header(
+    app: Sphinx, relative_path: Path, parent_docname: str, content: list[str]
+):
+    """Fill in the name of the document in the header.
+
+    When regression/header.md is read via the include directive, replace
+    {{ parent_docname }} with the name of the parent document that included
+    header.md.
+
+    Note: parent_docname does not include the file extension.
+
+    Here is a simplified example of how this works.
+
+    Contents of header.md:
+
+        {download}`Download {{ parent_docname }}.md <{{ parent_docname }}.md>`
+
+    Contents of foobar.md:
+
+        ```{include} header.md
+        ```
+
+    After this function and others are run...
+
+    Contents of foobar.md:
+
+        {download}`Download foobar.md <foobar.md>`
+    """
+    if not relative_path.match("regression/header.md"):
+        return
+
+    for i, value in enumerate(content):
+        content[i] = re.sub(parent_docname_substitution_re, parent_docname, value)
+
+
+def setup(app):
+    app.connect("config-inited", preprocess_notebooks)
+    app.connect("include-read", sub_parent_docname_in_header)
 
 # 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
@@ -38,6 +109,7 @@
 extensions = [
     'jupyterlite_sphinx',
     'matplotlib.sphinxext.plot_directive',
+    'myst_nb',
     'numpydoc',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
@@ -47,15 +119,19 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.todo',
     'sphinx_copybutton',
+    'sphinx_design',
     'sphinx_togglebutton',
-
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 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'
@@ -141,8 +217,8 @@
 "show_prev_next": True,
 "footer_start": ["copyright", "sphinx-version"],
 "footer_end": ["theme-version"],
-"pygment_light_style": "a11y-high-contrast-light",
-"pygment_dark_style": "a11y-high-contrast-dark",
+"pygments_light_style": "a11y-high-contrast-light",
+"pygments_dark_style": "a11y-high-contrast-dark",
 "icon_links": [
         {
             "name": "Discussion group on Google Groups",
@@ -200,6 +276,7 @@
 # _static directory.
 html_css_files = [
     "pywavelets.css",
+    "myst-nb.css"
 ]
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
@@ -278,7 +355,12 @@
 
 # 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/header.md',
+    'regression/README.md',
+    'regression/*.ipynb'  # exclude IPyNB files from the build
+]
 
 # numpydoc_show_class_members = False
 numpydoc_class_members_toctree = False
@@ -310,3 +392,25 @@
 Shall you encounter any issues, please feel free to report them on the
 [PyWavelets issue tracker](https://github.com/PyWavelets/pywt/issues)."""
 )
+
+jupyterlite_silence = True
+strip_tagged_cells = True
+
+# -- Options for MyST-NB and Markdown-based content --------------------------
+
+os.environ["PYDEVD_DISABLE_FILE_VALIDATION"] = "1"
+
+# https://myst-nb.readthedocs.io/en/latest/configuration.html
+nb_execution_mode = 'auto'
+nb_execution_timeout = 60
+nb_execution_allow_errors = False
+nb_execution_raise_on_error = True
+nb_render_markdown_format = "myst"
+nb_remove_code_source = False
+nb_remove_code_outputs = False
+
+myst_enable_extensions = [
+    'amsmath',
+    'colon_fence',
+    'dollarmath',
+]

doc/source/regression/README.md

@@ -0,0 +1,54 @@
+# Regression folder
+
+This folder contains various useful examples illustrating how to use and how not
+to use PyWavelets.
+
+The examples are written in the [MyST markdown notebook
+format](https://myst-nb.readthedocs.io/en/v0.13.2/use/markdown.html). This
+allows each .md file to function simultaneously as documentation that can be fed
+into Sphinx and as a source file that can be converted to the Jupyter notebook
+format (.ipynb), which can then be opened in notebook applications such as
+JupyterLab. For this reason, each example page in this folder includes a header template
+that adds a blurb to the top of each page about how the page can be
+run or downloaded as a Jupyter notebook.
+
+There a few shortcomings to this approach of generating the code cell outputs in
+the documentation pages at build time rather than hand editing them into the
+document source file. One is that we can no longer compare the generated outputs
+with the expected outputs as we used to do with doctest. Another is that we
+lose some control over how we want the outputs to appear, unless we use a workaround.
+
+Here is the workaround we created. First we tell MyST-NB to remove the generated
+cell output from the documentation page by adding the `remove-output` tag to the
+`code-cell` directive in the markdown file. Then we hand code the output in a
+`code-block` directive, not to be confused with `code-cell`! The `code-cell`
+directive says "I am notebook code cell input, run me!" The `code-block`
+directive says, "I am just a block of code for documentation purposes, don't run
+me!" To the code block, we add the `.pywt-handcoded-cell-output` class so that
+we can style it to look the same as other cell outputs on the same HTML page.
+Finally, we tag the handcoded output with `jupyterlite_sphinx_strip` so that we
+can exclude it when converting from .md to .ipynb. That way only generated
+output appears in the .ipynb notebook.
+
+To recap:
+
+- We use the `remove-output` tag to remove the **generated** code cell output
+  during .md to .html conversion (this conversion is done by MyST-NB).
+- We use the `jupyterlite_sphinx_strip` tag to remove the **handcoded** output
+  during .md to .ipynb conversion (this conversion is done by Jupytext).
+
+Example markdown:
+
+    ```{code-cell}
+    :tags: [raises-exception, remove-output]
+    1 / 0
+    ```
+
+    +++ {"tags" ["jupyterlite_sphinx_strip"]}
+
+    ```{code-block} python
+    :class: pywt-handcoded-cell-output
+    Traceback (most recent call last):
+    ...
+    ZeroDivisionError: division by zero
+    ```