Session: Sphinx-Gallery: Pimp your documentation with a gallery of examples


Documentation has possibly the biggest impact in converting your package into a software that is used by a large community. Often learning from runnable python examples is a great way to get started with a package, quickly grasp what you can do with it, how its different pieces fit together and experiment with the package to gain a deeper understanding of it.

One great example of this and a great asset of the matplotlib documentation is the matplotlib gallery. Historically quite a few packages have developed their own variation of an example gallery adapting it to suit their needs. Amongst the ones that we know of: matplotlib, scikit-learn, scikit-image, mne-python, nilearn, etc ... The goal of Sphinx-Gallery is to provide this functionality as a sphinx extension that can be reused across these projects.

Sphinx-Gallery is a Sphinx extension that can execute a selected set of python scripts, capture their output (text and figures), and generate HTML pages in which narrative prose is interleaved with the code and its output. On top of that a Jupyter notebook is generated for each example allowing users to run any example in this popular environment. All these individual examples are shown in a gallery which is a great way to showcase your package functionalities and where people can quickly spot visually what they are looking for.

Additional features include:

  • Automatic references from API documentation to the HTML examples which show how a particular function or class is used in the example

  • Error messages are shown in your Sphinx build output when running examples plus a summary at the end, keeping you informed tha - At all your examples run fine as you package evolves.

  • Example code scripts are parsed and functions/classes are turned into links to the relevant online documentation, making the example code easier to understand

  • Examples are easily referenceable from the rest of your Sphinx documentation

In this talk we'll describe Sphinx-Gallery main features and cover how to get started with Sphinx-Gallery and use it for your package documentation.