Creating an Example Notebook

Functionality of ProbNum is explained in detail in the form of Jupyter notebooks in the tutorials section of the documentation. If you want to add an example showcasing the functionality of ProbNum, follow the instructions below.

from IPython.display import Image

display(Image(url='https://upload.wikimedia.org/wikipedia/commons/thumb/3/38/Jupyter_logo.svg/1200px-Jupyter_logo.svg.png',
              width=250, embed=True))

Setting up the Jupyter Notebook

We begin by creating a new Jupyter notebook under ./docs/source/tutorials/. If you want some guidance on the style, you can copy one of the existing notebooks.

Style and HTML conversion

If you create your own ensure that the first cell is a markdown cell containing an upper level markdown header (# Header) to be converted correctly to HTML. This header will appear in the sidebar of the documentation. In the body of the notebook only use headers of a lower level (## and more) to ensure correct sidebar appearance.

In order to keep the style of the output consistent, the first code cell of the notebook should contain the following code snippet.

# Make inline plots vector graphics instead of raster graphics
%matplotlib inline
from IPython.display import set_matplotlib_formats

set_matplotlib_formats("pdf", "svg")

# Plotting
import matplotlib.pyplot as plt

plt.style.use("../probnum.mplstyle")

This snippet defines the style of plots generated by Matplotlib. For example, it defines the font and makes sure any output is a vector graphic. If you need to use specific LaTeX packages, e.g. to label your plots, simply add them to the list via:

plt.rcParams["text.latex.preamble"] += r" \usepackage{siunitx}"

plt.rcParams["text.latex.preamble"]

'\usepackage[cm]{sfmath} \usepackage{amsmath, amssymb} \usepackage{bm} \renewcommand{\familydefault}{\sfdefault} \usepackage{siunitx}'

Adding the Notebook to the Website

Now that you’ve created your notebook, we have to add it in the right place on the website. Check the existing topics in ./docs/source/tutorials/<some_topic>.rst and add your notebook name to the appropriate nbgallery.

.. nbgallery::

   my_example_notebook

This creates a gallery item on the corresponding topic page in the documentation under tutorials. You can set the preview image for your example notebook by choosing a cell that produces an output plot and adding a tag to the metadata of the corresponding Jupyter notebook cell.

{
    "tags": [
        "nbsphinx-thumbnail"
    ]
}

Viewing the Result

In order to view the resulting page from the notebook, build the documentation locally via

tox -e docs

If the notebook compiles successfully, you should see similar output to the one below.

...
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

Build finished. The HTML pages are in _build/html.
___________________________________ summary ____________________________________
  docs: commands succeeded
  congratulations :)

You can now view your results locally by opening the website in ./docs/_build/html. Make sure you fix any error messages popping up in the build before making a pull request to the main branch. Once you’ve created a pull request ReadTheDocs will automatically build the documentation including your new example notebook.