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:

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

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:

Image showing the gallery output provided by nbsphinx using the sphinx-gallery front end interface.

nbsphinx can be combined with Sphinx gallery to create a gallery of tutorials. However, rather render 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
            ...