From 874090cd5c334dd1c2ce67505f4aa6da71e9434f Mon Sep 17 00:00:00 2001 From: gabalafou Date: Fri, 20 Dec 2024 04:14:50 -0600 Subject: [PATCH] Provide JupyterLite and download links via include file --- doc/source/_static/pywavelets.css | 49 +++++++++++++++++++---------- doc/source/conf.py | 45 ++++++++++++++++++++++++-- doc/source/regression/dwt-idwt.md | 20 +----------- doc/source/regression/gotchas.md | 20 +----------- doc/source/regression/header.md | 13 ++++++++ doc/source/regression/modes.md | 20 +----------- doc/source/regression/multilevel.md | 20 +----------- doc/source/regression/wavelet.md | 20 +----------- doc/source/regression/wp.md | 20 +----------- doc/source/regression/wp2d.md | 20 +----------- 10 files changed, 95 insertions(+), 152 deletions(-) create mode 100644 doc/source/regression/header.md diff --git a/doc/source/_static/pywavelets.css b/doc/source/_static/pywavelets.css index 56f12e4df..fcff86097 100644 --- a/doc/source/_static/pywavelets.css +++ b/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; } diff --git a/doc/source/conf.py b/doc/source/conf.py index bd4c7a75b..f054537f0 100644 --- a/doc/source/conf.py +++ b/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,6 +39,8 @@ 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: @@ -47,8 +48,47 @@ def preprocess_notebooks(app: Sphinx, *args, **kwargs): 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 ` + """ + 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 ] diff --git a/doc/source/regression/dwt-idwt.md b/doc/source/regression/dwt-idwt.md index 92289ff88..003cc1d0e 100644 --- a/doc/source/regression/dwt-idwt.md +++ b/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) ` - 2. :download:`Download Markdown Notebook (Jupytext) ` +```{include} header.md ``` +++ diff --git a/doc/source/regression/gotchas.md b/doc/source/regression/gotchas.md index 6d3b4719f..b5615a25a 100644 --- a/doc/source/regression/gotchas.md +++ b/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) ` - 2. :download:`Download Markdown Notebook (Jupytext) ` +```{include} header.md ``` +++ diff --git a/doc/source/regression/header.md b/doc/source/regression/header.md new file mode 100644 index 000000000..e2ba11988 --- /dev/null +++ b/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>` +```` diff --git a/doc/source/regression/modes.md b/doc/source/regression/modes.md index 38ea50b07..3f333ae87 100644 --- a/doc/source/regression/modes.md +++ b/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) ` - 2. :download:`Download Markdown Notebook (Jupytext) ` +```{include} header.md ``` +++ diff --git a/doc/source/regression/multilevel.md b/doc/source/regression/multilevel.md index dde825d41..8bcd41152 100644 --- a/doc/source/regression/multilevel.md +++ b/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) ` - 2. :download:`Download Markdown Notebook (Jupytext) ` +```{include} header.md ``` +++ diff --git a/doc/source/regression/wavelet.md b/doc/source/regression/wavelet.md index 03a52a9c2..f4509056a 100644 --- a/doc/source/regression/wavelet.md +++ b/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) ` - 2. :download:`Download Markdown Notebook (Jupytext) ` +```{include} header.md ``` +++ diff --git a/doc/source/regression/wp.md b/doc/source/regression/wp.md index 5c230cdae..17a091207 100644 --- a/doc/source/regression/wp.md +++ b/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) ` - 2. :download:`Download Markdown Notebook (Jupytext) ` +```{include} header.md ``` +++ diff --git a/doc/source/regression/wp2d.md b/doc/source/regression/wp2d.md index 98d78d48e..a4fd4227d 100644 --- a/doc/source/regression/wp2d.md +++ b/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) ` - 2. :download:`Download Markdown Notebook (Jupytext) ` +```{include} header.md ``` +++