From 043c3ca4afe8a32727d040be8903a61d927e5faf Mon Sep 17 00:00:00 2001 From: Frankie Robertson Date: Mon, 9 Mar 2026 11:43:10 +0200 Subject: [PATCH 1/5] Renumber Sphinx-4 => Sphinx-3 --- content/sphinx.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/sphinx.md b/content/sphinx.md index 06f2eda..a35485d 100644 --- a/content/sphinx.md +++ b/content/sphinx.md @@ -334,7 +334,7 @@ extensions = ['myst_parser', 'sphinx.ext.mathjax'] ## Exercise: Sphinx autodoc -`````{exercise} (optional) Sphinx-4: Auto-generating documentation from Python docstrings +`````{exercise} Sphinx-3: Auto-generating documentation from Python docstrings 1. Write some docstrings in functions and/or class definitions of an `example` python module: ```python From e5e24074a7184b4b9795ded4d34e401cb6a79ba0 Mon Sep 17 00:00:00 2001 From: Frankie Robertson Date: Mon, 9 Mar 2026 11:44:21 +0200 Subject: [PATCH 2/5] Clarify autodocs instructions --- content/sphinx.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/content/sphinx.md b/content/sphinx.md index a35485d..1613fd8 100644 --- a/content/sphinx.md +++ b/content/sphinx.md @@ -336,7 +336,7 @@ extensions = ['myst_parser', 'sphinx.ext.mathjax'] `````{exercise} Sphinx-3: Auto-generating documentation from Python docstrings -1. Write some docstrings in functions and/or class definitions of an `example` python module: +1. Write some docstrings in functions and/or class definitions to a python module `multiply.py`: ```python def multiply(a: float, b: float) -> float: """ @@ -349,7 +349,7 @@ def multiply(a: float, b: float) -> float: return a * b ``` -2. In the file `conf.py` modify "extensions" and add 3 lines: +2. In the file `conf.py` modify "extensions" and add the `autodoc2_packages` with `"multiply.py"`: ```python extensions = ['myst_parser', "autodoc2"] @@ -357,14 +357,15 @@ autodoc2_packages = [ "multiply.py" ] ``` +If you already have extensions from another exercise, just add `"autodoc2"` to the existing list. -4. List `apidocs/index` in the toctree in `index.rst`. +4. Add `apidocs/index` to the toctree in `index.rst`. ```rst .. toctree:: :maxdepth: 2 :caption: Contents: - some-feature.md + ... apidocs/index ``` From 335e216e098739b73a8d11b79da3650ae9cd9010 Mon Sep 17 00:00:00 2001 From: Frankie Robertson Date: Mon, 9 Mar 2026 11:54:24 +0200 Subject: [PATCH 3/5] Remove note about myst-nb since exercise will be added --- content/sphinx.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/content/sphinx.md b/content/sphinx.md index 1613fd8..9471c0a 100644 --- a/content/sphinx.md +++ b/content/sphinx.md @@ -299,9 +299,6 @@ int main() ``` ```` -- We can also use Jupyter notebooks (*.ipynb) with Sphinx. It requires the - [myst-nb](https://myst-nb.readthedocs.io/) extension to be installed. - - Math equations with LaTeX should work out of the box. Try this (result below): ````markdown This creates an equation: From ac4524866d6e342f46ecf86b84e1958c496dc86e Mon Sep 17 00:00:00 2001 From: Frankie Robertson Date: Mon, 9 Mar 2026 11:55:29 +0200 Subject: [PATCH 4/5] Add myst-nb exercise --- content/sphinx.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/content/sphinx.md b/content/sphinx.md index 9471c0a..7bc9f71 100644 --- a/content/sphinx.md +++ b/content/sphinx.md @@ -370,6 +370,55 @@ If you already have extensions from another exercise, just add `"autodoc2"` to t ````` +## Exercise: Using Jupyter with Sphinx + +`````{exercise} Sphinx-4: Writing Sphinx content with Jupyter + +1. Create a text-based notebook files `flower.md` in the same directory as the `index.rst` file. This file will be converted to a Jupyter notebook by the `myst_nb` Sphinx extension and then executed by Jupyter. Fill the file with the following content: +````md +--- +file_format: mystnb +kernelspec: + name: python3 +--- +# Flower plot + +```{code-cell} ipython3 +import matplotlib.pyplot as plt +import numpy as np + +fig, ax = plt.subplots(1, 1, figsize=(5, 8), subplot_kw={"projection": "polar"}) +theta = np.arange(0, 2 * np.pi, 0.01) +r = np.sin(5 * theta) +ax.set_rticks([]) +ax.set_thetagrids([]) +ax.plot(theta, r); +ax.plot(theta, np.full(len(theta), -1)); +``` +```` + +2. In the file `conf.py` modify `extensions` to remove `"myst_parser"` and add `"myst_nb"` (you will get an error if you include both): +```python +extensions = ["myst_nb"] +``` +Note that MyST parser functionality is included in MyST NB, so everything else will continue to work as before. + +3. List `flower` in the toctree in `index.rst`. +```rst +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + ... + flower.md +``` + +4. Re-build the documentation and check the "Flower" section. + +5. (Optional) As an alternative to including a text-based notebook with an `.md` file in your documentation, you can add a `.ipynb` files saved from Jupyter notebook or Jupyter lab. Just make sure to 1) start the notebook with a markdown cell with a `# Title` so it can be included in the table of contents 2) save the notebook in the same directory as `index.rst` and 3) list it in the toctree in `index.rst`. + +````` + ## Confused about reStructuredText vs. Markdown vs. MyST? - At the beginning there was reStructuredText and Sphinx was built for reStructuredText. From b6fe1c8bc7b5fe6fa65a21efd81bf0972fd76b0d Mon Sep 17 00:00:00 2001 From: Frankie Robertson Date: Tue, 10 Mar 2026 13:42:45 +0200 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Michele Mesiti --- content/sphinx.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/content/sphinx.md b/content/sphinx.md index 7bc9f71..881cfb3 100644 --- a/content/sphinx.md +++ b/content/sphinx.md @@ -346,7 +346,7 @@ def multiply(a: float, b: float) -> float: return a * b ``` -2. In the file `conf.py` modify "extensions" and add the `autodoc2_packages` with `"multiply.py"`: +2. In the file `conf.py` add `autodoc2` to the "extensions", and add the list `autodoc2_packages` which will mention `"multiply.py"`: ```python extensions = ['myst_parser', "autodoc2"] @@ -374,7 +374,7 @@ If you already have extensions from another exercise, just add `"autodoc2"` to t `````{exercise} Sphinx-4: Writing Sphinx content with Jupyter -1. Create a text-based notebook files `flower.md` in the same directory as the `index.rst` file. This file will be converted to a Jupyter notebook by the `myst_nb` Sphinx extension and then executed by Jupyter. Fill the file with the following content: +1. For simplicity, create a text-based notebook files `flower.md` in the same directory as the `index.rst` file. This file will be converted to a Jupyter notebook by the `myst_nb` Sphinx extension and then executed by Jupyter. Fill the file with the following content: ````md --- file_format: mystnb @@ -396,8 +396,8 @@ ax.plot(theta, r); ax.plot(theta, np.full(len(theta), -1)); ``` ```` - -2. In the file `conf.py` modify `extensions` to remove `"myst_parser"` and add `"myst_nb"` (you will get an error if you include both): +Note that there needs to be a title in the notebook (a heading starting with a single `#`), that will be used as an entry and link in the table of content. +2. In the file `conf.py` modify `extensions` to remove `"myst_parser"` and add `"myst_nb"` ([you will get an error if you include both](https://myst-nb.readthedocs.io/en/latest/quickstart.html)): ```python extensions = ["myst_nb"] ``` @@ -415,7 +415,9 @@ Note that MyST parser functionality is included in MyST NB, so everything else w 4. Re-build the documentation and check the "Flower" section. -5. (Optional) As an alternative to including a text-based notebook with an `.md` file in your documentation, you can add a `.ipynb` files saved from Jupyter notebook or Jupyter lab. Just make sure to 1) start the notebook with a markdown cell with a `# Title` so it can be included in the table of contents 2) save the notebook in the same directory as `index.rst` and 3) list it in the toctree in `index.rst`. +5. You can add a `.ipynb` files saved from Jupyter notebook or Jupyter lab. Just make sure to list it in the toctree in `index.rst` with the correct path. + +If you have problems, consider cleaning manually the `jupyter_execute` directory. `````