What is Sphinx-Gallery ?

It's an extension that builds an HTML version of any python script and puts it into an examples gallery.

• Documentation has possibly the biggest impact in converting your

package into software that is used by a large community.

• For python developers, Sphinx is our go to tool at the moment of

documenting our software.

• Text

You are certainly familiar with this

http://matplotlib.org/gallery.html

A great example of this asset is the matplotlib documentation with its gallery. Learning from examples is a great way to get started with a package and quickly grasp what you can do with it.

The visual search is also great. Sometimes you don't know what you want or how it's called until it is in front of your eyes.

Many python packages imitated this model, and developed their own solutions. The goal of Sphinx-Gallery is to unify all these gallery generators in one code base, centralize the development effort and share it, so that everyone can benefit from it.

Now you can have it too!!

And Better with Sphinx-Gallery

• The Gallery building is completely automated. You just worry about: writing nice examples
• Avoids repetition
  • Source code and documentation are the same python file
  • Every example receives a reference link name
• Interleave prose, code and output as much as you want. Notebook styled examples
• Your examples can be downloaded as python source files & Jupyter Notebooks
• Visible error messages when your examples don't build correctly
• Automatically link from your API documentation to examples using the functions

Who uses it already?

Goaled at the nilearn and scikit-learn projects. It branched from those two custom gallery generators into an independent package. Most of the gallery development came first from original project developers. Now it's mostly maintained by me.

How does it look?

https://sphinx-gallery.readthedocs.io

From API to Examples

http://nilearn.github.io/

Setting up your Project

awesome_python_project
├── doc
│   ├── conf.py
│   ├── index.rst
│   └── Makefile
├── examples
│   ├── README.txt
│   └── plot_colors.py
...

Introduce your Gallery in examples/README.txt

.. _My_Gallery:

My Gallery
==========

Colormaps Examples
------------------

Colormap examples using Sphinx-Gallery

Your examples in Python

With the plot_ prefix Sphinx-Gallery executes the script

# -*- coding: utf-8 -*-
r"""
===============================
Colormaps alter your perception
===============================

Here I plot the function

.. math:: f(x, y) = \sin(x) + \cos(y)

with different colormaps.

"""

import numpy as np
import matplotlib.pyplot as plt

x = np.linspace(-np.pi, np.pi, 300)
xx, yy = np.meshgrid(x, x)
z = np.cos(xx) + np.cos(yy)

plt.figure()
plt.imshow(z)

plt.figure()
plt.imshow(z, cmap=plt.cm.get_cmap('hot'))

plt.figure()
plt.imshow(z, cmap=plt.cm.get_cmap('Spectral'),
           interpolation='none')

# Not needed for the Gallery.
# Only for direct execution
plt.show()

################################################
# You can define blocks in your source code
# with interleaving prose.
#

print("This writes to stdout and will be",
      " displayed in the HTML file")

Setting up Sphinx-Gallery

Install it with:

$ pip install sphinx-gallery

Edit the doc/conf.py file with

import sphinx_gallery
extensions = [
    ...
    'sphinx_gallery.gen_gallery',
    ]

sphinx_gallery_conf = {
    # path to your examples scripts
    'examples_dirs' : '../examples',
    # path where to save gallery generated examples
    'gallery_dirs'  : 'auto_examples'}

Build the Documentation

$ make html

Thank you for your attention

Start using and contributing to Sphinx-Gallery