Provide JupyterLite and download links via include file

doc/source/_static/pywavelets.css

@@ -1,27 +1,42 @@
 /* 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.
+
+We use "tip" admonitions at the top of each doc in the regression/ directory.
+This rule removes the top margin for tip admonitions when they occur as the very
+first child of some container. This will not affect non-first-child tip
+admonitions.
+*/
+.admonition.tip:first-child {
+  margin-top: 0;
 }

doc/source/conf.py

@@ -11,11 +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
@@ -40,15 +39,56 @@ def preprocess_notebooks(app: Sphinx, *args, **kwargs):
 
     print("Converting Markdown files to IPyNB...")
     for path in (HERE / "regression").glob("*.md"):
+        if path.match("regression/header.md"):
+            continue
         nb = jupytext.read(str(path))
         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
@@ -309,6 +349,7 @@ def setup(app):
 # directories to ignore when looking for source files.
 exclude_patterns = [
     'substitutions.rst',
+    'regression/header.md',
     'regression/*.ipynb'  # exclude IPyNB files from the build
 ]
 

doc/source/regression/dwt-idwt.md

@@ -16,25 +16,7 @@ mystnb:
 
 +++ {"tags": ["jupyterlite_sphinx_strip"]}
 
-```{eval-rst}
-.. currentmodule:: pywt
-
-.. dropdown:: 🧑‍🔬 This notebook can be executed online. Click this section to try it out! ✨
-    :color: success
-
-    .. notebooklite:: dwt-idwt.ipynb
-      :width: 100%
-      :height: 600px
-      :prompt: Open notebook
-
-.. dropdown:: Download this notebook
-    :color: info
-    :open:
-
-    Please use the following links to download this notebook in various formats:
-
-    1. :download:`Download IPyNB (IPython Notebook) <dwt-idwt.ipynb>`
-    2. :download:`Download Markdown Notebook (Jupytext) <dwt-idwt.md>`
+```{include} header.md
 ```
 
 +++

doc/source/regression/gotchas.md

@@ -13,25 +13,7 @@ kernelspec:
 
 +++ {"tags": ["jupyterlite_sphinx_strip"]}
 
-```{eval-rst}
-.. currentmodule:: pywt
-
-.. dropdown:: 🧑‍🔬 This notebook can be executed online. Click this section to try it out! ✨
-    :color: success
-
-    .. notebooklite:: gotchas.ipynb
-      :width: 100%
-      :height: 600px
-      :prompt: Open notebook
-
-.. dropdown:: Download this notebook
-    :color: info
-    :open:
-
-    Please use the following links to download this notebook in various formats:
-
-    1. :download:`Download IPyNB (IPython Notebook) <gotchas.ipynb>`
-    2. :download:`Download Markdown Notebook (Jupytext) <gotchas.md>`
+```{include} header.md
 ```
 
 +++

doc/source/regression/header.md

@@ -0,0 +1,13 @@
+````{tip}
+
+This page can also be run or downloaded as a notebook.
+
+```{jupyterlite} {{ parent_docname }}.ipynb
+:new_tab: True
+```
+
+Downloads:
+
+1. {download}`Download {{ parent_docname }}.ipynb <{{ parent_docname }}.ipynb>`
+2. {download}`Download {{ parent_docname }}.md <{{ parent_docname }}.md>`
+````

doc/source/regression/modes.md

@@ -13,25 +13,7 @@ kernelspec:
 
 +++ {"tags": ["jupyterlite_sphinx_strip"]}
 
-```{eval-rst}
-.. currentmodule:: pywt
-
-.. dropdown:: 🧑‍🔬 This notebook can be executed online. Click this section to try it out! ✨
-    :color: success
-
-    .. notebooklite:: modes.ipynb
-      :width: 100%
-      :height: 600px
-      :prompt: Open notebook
-
-.. dropdown:: Download this notebook
-    :color: info
-    :open:
-
-    Please use the following links to download this notebook in various formats:
-
-    1. :download:`Download IPyNB (IPython Notebook) <modes.ipynb>`
-    2. :download:`Download Markdown Notebook (Jupytext) <modes.md>`
+```{include} header.md
 ```
 
 +++

doc/source/regression/multilevel.md

@@ -13,25 +13,7 @@ kernelspec:
 
 +++ {"tags": ["jupyterlite_sphinx_strip"]}
 
-```{eval-rst}
-.. currentmodule:: pywt
-
-.. dropdown:: 🧑‍🔬 This notebook can be executed online. Click this section to try it out! ✨
-    :color: success
-
-    .. notebooklite:: multilevel.ipynb
-      :width: 100%
-      :height: 600px
-      :prompt: Open notebook
-
-.. dropdown:: Download this notebook
-    :color: info
-    :open:
-
-    Please use the following links to download this notebook in various formats:
-
-    1. :download:`Download IPyNB (IPython Notebook) <multilevel.ipynb>`
-    2. :download:`Download Markdown Notebook (Jupytext) <multilevel.md>`
+```{include} header.md
 ```
 
 +++

doc/source/regression/wavelet.md

@@ -13,25 +13,7 @@ kernelspec:
 
 +++ {"tags": ["jupyterlite_sphinx_strip"]}
 
-```{eval-rst}
-.. currentmodule:: pywt
-
-.. dropdown:: 🧑‍🔬 This notebook can be executed online. Click this section to try it out! ✨
-    :color: success
-
-    .. notebooklite:: wavelet.ipynb
-      :width: 100%
-      :height: 600px
-      :prompt: Open notebook
-
-.. dropdown:: Download this notebook
-    :color: info
-    :open:
-
-    Please use the following links to download this notebook in various formats:
-
-    1. :download:`Download IPyNB (IPython Notebook) <wavelet.ipynb>`
-    2. :download:`Download Markdown Notebook (Jupytext) <wavelet.md>`
+```{include} header.md
 ```
 
 +++

doc/source/regression/wp.md

@@ -13,25 +13,7 @@ kernelspec:
 
 +++ {"tags": ["jupyterlite_sphinx_strip"]}
 
-```{eval-rst}
-.. currentmodule:: pywt
-
-.. dropdown:: 🧑‍🔬 This notebook can be executed online. Click this section to try it out! ✨
-    :color: success
-
-    .. notebooklite:: wp.ipynb
-      :width: 100%
-      :height: 600px
-      :prompt: Open notebook
-
-.. dropdown:: Download this notebook
-    :color: info
-    :open:
-
-    Please use the following links to download this notebook in various formats:
-
-    1. :download:`Download IPyNB (IPython Notebook) <wp.ipynb>`
-    2. :download:`Download Markdown Notebook (Jupytext) <wp.md>`
+```{include} header.md
 ```
 
 +++

doc/source/regression/wp2d.md

@@ -13,25 +13,7 @@ kernelspec:
 
 +++ {"tags": ["jupyterlite_sphinx_strip"]}
 
-```{eval-rst}
-.. currentmodule:: pywt
-
-.. dropdown:: 🧑‍🔬 This notebook can be executed online. Click this section to try it out! ✨
-    :color: success
-
-    .. notebooklite:: wp2d.ipynb
-      :width: 100%
-      :height: 600px
-      :prompt: Open notebook
-
-.. dropdown:: Download this notebook
-    :color: info
-    :open:
-
-    Please use the following links to download this notebook in various formats:
-
-    1. :download:`Download IPyNB (IPython Notebook) <wp2d.ipynb>`
-    2. :download:`Download Markdown Notebook (Jupytext) <wp2d.md>`
+```{include} header.md
 ```
 
 +++