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.