Including Jupyter notebooks in documentation#

Rubin Observatory user guides can include pages written as Jupyter notebooks. Jupyter notebooks are ideal for including tutorials and examples in your documentation content. Internally, Documenteer uses MyST-NB to parse Jupyter Notebooks into Sphinx content. Prose cells in Jupyter notebooks use the MyST markdown syntax so that they can use Sphinx directives and roles (see Using Markdown syntax in Rubin Observatory documentation).

Using ipynb files as content pages#

To include a Jupyter notebook as a page in the documentation, add and commit its ipynb file to the documentation repository like you would a reStructuredText (.rst) or markdown (.md) file. Then include that .ipynb notebook file in a toctree directive. Like regular pages, notebook pages are listed in toctree with their file names, but without the file extension:

.. toctree::
   :maxdepth: 1

   my-notebook

Computation#

Unlike regular markdown and reStructuredText pages, Jupyter notebooks can contain executable code cells. By default, Documenteer uses MyST-NB’s auto setting so that notebooks with missing outputs are executed when the documentation is built. Alternatively, if the notebook is present with all outputs it will not be executed.

Pre-executing notebooks that rely on the RSP#

If your notebook relies on running in the Notebook Aspect of the Rubin Science Platform, you currently cannot execute that notebook in the GitHub Actions environment that Rubin documentation is built in. In this case, you must execute the notebook on the Rubin Science Platform, and commit that executed notebook to your documentation repository. By default, the notebook will not be re-executed during the Sphinx build when outputs are already present.

Examples#

Here is a Python code cell with its output computed during the documentation build:

for i in range(5):
    print(i * 2)

0
2
4
6
8

Further reading#