A Sphinx extension that builds an HTML gallery of examples from any set of Python scripts. Checkout the documentation for introductions on how to use it and more...
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 checkout the
documentation for introductions on how to use it and more...
You can do a direct install via pip
by using:
$ pip install sphinx-gallery "sphinx>=4.0" pillow
Important
Sphinx-Gallery will not manage its dependencies when installing, thus you are required to install them manually. Our minimal dependencies are Sphinx >= 4 and Pillow, which we use for scaling images.
Tip
Sphinx-Gallery also has support for scraping images from Matplotlib and Matplotlib-based packages such as Seaborn. We recommend installing system optipng
binaries to reduce the file sizes of the generated PNG files.
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.
An incomplete list:
- Apache TVM
- Astropy
- auto-sklearn
- Biotite
- Cartopy
- FURY
- pyGIMLi
- HyperSpy
- kikuchipy
- Matplotlib
- MNE-Python
- 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
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
$ pip install -r requirements.txt -r dev-requirements.txt
$ conda install graphviz # if using conda, you can get graphviz this way
$ pip install -e .
Check that you are all set by running:
$ pytest sphinx_gallery
If you would like to cite Sphinx-Gallery you can do so using our Zenodo deposit.