Create tutorials in your Python package documentation

Your package should have tutorials that make it easy for a user to get started using your package. Ideally, those tutorials also can be run from start to finish providing a second set of checks (on top of your test suite) to your package’s code base.

On this page, we review two Sphinx extensions (sphinx-gallery and nbsphinx) that allow you to create reproducible tutorials that are run when your Sphinx documentation builds.

Create Python package tutorials that run when you build your docs

Adding well constructed tutorials to your package will make it easier for someone new to begin using your package.

There are two Sphinx tools that make it easy to add tutorials to your package:

• Sphinx Gallery and

• NbSphinx

Both of these tools act as Sphinx extensions and:

• Support creating a gallery type page in your Sphinx documentation where users can explore tutorials via thumbnails.

• Run the code in your tutorials adding another level of “testing” for your package as used.

• Render your tutorials with Python code and plot outputs

sphinx gallery:

If you prefer to write your tutorials using Python .py scripts, you may enjoy using Sphinx gallery. Sphinx gallery uses .py files with text and code sections that mimic the Jupyter Notebook format. When you build your documentation, the gallery extension:

1. Runs the code in each tutorial. Running your tutorial like this acts as a check to ensure your package’s functions, classes, methods, and attributes (ie the API) are working as they should.

2. Creates a downloadable Jupyter Notebook .ipynb file and a .py script for your tutorial that a user can quickly download and run.

3. Creates a rendered .html page with the code elements and code outputs in a user-friendly tutorial gallery.

4. Creates a gallery landing page with visual thumbnails for each tutorial that you create.

sphinx-gallery makes it easy to create a user-friendly tutorial gallery. Each tutorial has a download link where the user can download a .py file or a Jupyter Notebook. And it renders the tutorials in a user-friendly grid.

Below you can see what a tutorial looks like created with sphinx-gallery.

sphinx-gallery tutorials by default include download links for both the python script (.py file) and a Jupyter notebook (.ipynb file) at the bottom.

Sphinx Gallery benefits

• easy-to-download notebook and .py outputs for each tutorials.

• .py files are easy to work with in the GitHub pull request environment.

• Nice gridded gallery output.

• Build execution time data per tutorial. Example

Sphinx gallery challenges

The downsides of using Sphinx gallery include:

• the .py files can be finicky to configure, particularly if you have matplotlib plot outputs.

For example: To allow for plots to render, you need to name each file with plot_ at the beginning.

• Many users these days are used to working in Jupyter Notebooks. .py may be slightly less user friendly to work with

These nuances can make it challenging for potential contributors to add tutorials to your package. This can also present maintenance challenge.

Add about the gallery setup:

$ docs % make html

Sphinx-Gallery successfully executed 2 out of 2 files

File directory structure:

tutorials/
    index.rst # landing page for your gallery
    plot_tutorial.py # a tutorial
    plot_tutorial-2.py # a tutorial that produces a plot output
_build/
    build_examples/ # This is where the downloadable tutorial files live
        plot_sample-1.ipynb
        plot_sample-1.py
        ...
    html/
        built_examples/ # You can specify this dir name in gallery settings
            index.html
            plot_sample-1.html
            plot_sample.html
            sg_execution_times.html # in case you want to see build times for each tutorial

nbsphinx - tutorials using Jupyter Notebooks

If you prefer to use Jupyter Notebooks to create tutorials you can use nbsphinx. nbsphinx operates similarly to Sphinx gallery in that:

• It runs your notebooks and produces outputs in the rendered tutorials

• Pro/con By default it does not support downloading of .py and .ipynb files. However you can add a link to the notebook at the top of the page with some additional conf.py settings (see: epilog settings)

nbsphinx can be combined with Sphinx gallery to create a gallery of tutorials. However, rather than rendering the gallery as a grid, it lists all of the gallery elements in a single column.

tutorials/
    index.md # Landing page for your gallery
    tutorial.ipynb # A tutorial in a jupyter notebook
    another_tutorial.ipynb
# This shows you what the build directory looks like when you build with sphinx-build
_build/
    html/
        # Notice that nbsphinx runs each notebook and produces an
        # html file with all of the outputs of your code
        # you can link to the notebook in your docs by modifying
        # the nbsphinx build - we will cover this in a separate tutorial series focused onPythonpackaging!
        tutorials/
            index.html
            index.md
            plot_sample-2.html
            plot_sample-2.ipynb
            ...