Sphinx-Gallery


A Sphinx extension that builds an HTML gallery of examples from any set of Python scripts. Check out the documentation for introductions on how to use it and more...

Quickstart

Sphinx-Gallery can be used to generate an example gallery from .py files, for a library, as well as a stand-alone web page showcasing examples of a particular Python package, module, or class.

Let's get started with a simple example or check out the
documentation for introductions on how to use it and more...

Install via pip

You can do a direct install via pip by using:

$ pip install sphinx-gallery

Add examples to your docs

Let's assume simple scenario, you have a Python package with a directory structure like this:

├── doc
│   ├── conf.py
│   ├── index.rst
|   ├── make.bat
│   └── Makefile
├── my_python_module
│   ├── __init__.py
│   └── mod.py
└── examples
    ├── plot_example.py
    └── README.txt (or .rst)

Enable Sphinx-Gallery by adding the following to your doc/conf.py:

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

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

Finally just compile your docs as usual. Sphinx-Gallery will generate reST files, adding execution outputs, and save them in auto_examples/. Add a link to auto_examples/index.rst to include the gallery in your documentation.

Who uses Sphinx-Gallery

An incomplete list:

• Apache TVM
• Astropy
• auto-sklearn
• Biotite
• Cartopy
• FURY
• pyGIMLi
• HyperSpy
• kikuchipy
• Matplotlib
• MNE-Python
• napari
• Nestle
• NetworkX
• Neuraxle
• Nilearn
• OpenML
• OpenTURNS
• Optuna
• PlasmaPy
• PyGMT
• pyRiemann
• PyStruct
• PySurfer
• PyTorch tutorials
• PyVista
• pyxem
• RADIS
• scikit-image
• scikit-learn
• SimPEG
• Sphinx-Gallery
• SunPy
• Tonic
• TorchIO

Contributing

You can get the latest development source from our Github repository. You need setuptools installed in your system to install Sphinx-Gallery. For example, you can do:

$ git clone https://github.com/sphinx-gallery/sphinx-gallery
$ cd sphinx-gallery
$ conda install graphviz  # if using conda, you can get graphviz this way
$ pip install -e .[dev]

Check that you are all set by running:

$ pytest sphinx_gallery

How to cite

If you would like to cite Sphinx-Gallery you can do so using our Zenodo deposit.