Adding 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.

Creating the Notebook

We begin by creating a new Jupyter notebook under ./docs/source/tutorials/. If you want some guidance on the style, simply copy one of the existing notebooks. 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.

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.rcParams['font.size'] = 18
plt.rcParams['text.usetex'] = True
plt.rcParams['text.latex.preamble'] = [r'\usepackage{amsfonts}',
                                       r'\usepackage{amsmath}',
                                       r'\usepackage{bm}']

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 plt.rcParams['text.latex.preamble'].

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 categories in ./docs/source/tutorials/tutorials.rst and add your notebook name under the appropriate header. If you want to add a new category, use the following restructuredText snippet to add a new table of contents linking to your notebook:

.. toctree::
   :maxdepth: 2
   :caption: My Example Category:

   my_example_notebook

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 output similar to:

...
copying notebooks ... [100%] tutorials/uncertainties_odefilter.ipynb
highlighting module code... [ 27%] probnum.filtsmooth.gaussfiltsmooth.extendedka
highlighting module code... [ 30%] probnum.filtsmooth.gaussfiltsmooth.gaussfilts
...
highlighting module code... [ 47%] probnum.filtsmooth.statespace.discrete.discre
highlighting module code... [100%] scipy.sparse.linalg.interface
writing additional pages...  searchdone
copying images... [  3%] tutorials/../../_build/html/.doctrees/nbsphinx/tutorial
copying images... [  7%] tutorials/../../_build/html/.doctrees/nbsphinx/tutorial
...
copying images... [ 96%] tutorials/../../_build/html/.doctrees/nbsphinx/tutorial
copying images... [100%] tutorials/../../_build/html/.doctrees/nbsphinx/tutorial
s_uncertainties_odefilter_10_0.svg
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

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 master branch. Once your pull request has been merged, Travis will automatically build the documentation including your new example notebook.