https://github.com/sphinx-gallery/sphinx-gallery

Sphinx extension for automatic generation of an example gallery
https://github.com/sphinx-gallery/sphinx-gallery

documentation examples gallery gallery-extension python sphinx sphinx-extension

Last synced: 3 months ago
JSON representation

Sphinx extension for automatic generation of an example gallery

• Host: GitHub
• URL: https://github.com/sphinx-gallery/sphinx-gallery
• Owner: sphinx-gallery
• License: bsd-3-clause
• Created: 2014-10-28T08:41:46.000Z (over 11 years ago)
• Default Branch: master
• Last Pushed: 2025-10-21T05:04:15.000Z (3 months ago)
• Last Synced: 2025-10-21T07:09:20.282Z (3 months ago)
• Topics: documentation, examples, gallery, gallery-extension, python, sphinx, sphinx-extension
• Language: Python
• Homepage: https://sphinx-gallery.github.io
• Size: 3.35 MB
• Stars: 442
• Watchers: 13
• Forks: 208
• Open Issues: 122
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGES.rst
  • License: LICENSE

Awesome Lists containing this project

README

          
==============

Sphinx-Gallery

==============

.. image:: https://img.shields.io/pypi/v/sphinx-gallery

    :target: https://pypi.org/project/sphinx-gallery/

    :alt: PyPI

.. image:: https://img.shields.io/conda/vn/conda-forge/sphinx-gallery

    :target: https://anaconda.org/conda-forge/sphinx-gallery

    :alt: Conda-forge

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3741780.svg

    :target: https://doi.org/10.5281/zenodo.3741780

    :alt: Zenodo DOI

.. image:: https://dev.azure.com/sphinx-gallery/sphinx-gallery/_apis/build/status/sphinx-gallery.sphinx-gallery?branchName=master

    :target: https://dev.azure.com/sphinx-gallery/sphinx-gallery/_build/latest?definitionId=1&branchName=master

    :alt: Azure CI status

.. image:: https://circleci.com/gh/sphinx-gallery/sphinx-gallery.svg?style=shield

    :target: https://circleci.com/gh/sphinx-gallery/sphinx-gallery

    :alt: CircleCI status

.. image:: https://codecov.io/github/sphinx-gallery/sphinx-gallery/badge.svg?branch=master&service=github(

    :target: https://app.codecov.io/github/sphinx-gallery/sphinx-gallery

    :alt: Code coverage

.. tagline-begin-content

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...

.. tagline-end-content

.. image:: doc/_static/demo.png

   :width: 80%

   :alt: A demo of a gallery generated by Sphinx-Gallery

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``

-------------------

.. installation-begin-content

You can do a direct install via ``pip`` by using:

.. code-block:: bash

    $ pip install sphinx-gallery

.. 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.

.. installation-end-content

Add examples to your docs

-------------------------

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

.. code-block::

    ├── 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``:

.. code-block:: python

    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:

.. projects_list_start

* `Apache TVM `_

* `Astropy `_

* `auto-sklearn `_

* `Biotite `_

* `Cartopy `_

* `FURY `_

* `pyGIMLi `_

* `HyperSpy `_

* `kikuchipy `_

* `Matplotlib `_

* `MNE-Python `_

* `napari `_

* `Nestle `_

* `NetworkX `_

* `Neuraxle `_

* `Nilearn `_

* `OpenML `_

* `OpenTURNS `_

* `Optuna `_

* `PlasmaPy `_

* `POT `_

* `PyGMT `_

* `pyRiemann `_

* `PyStruct `_

* `PySurfer `_

* `PyTorch tutorials `_

* `PyVista `_

* `pyxem `_

* `RADIS `_

* `scikit-image `_

* `scikit-learn `_

* `SimPEG `_

* `SKADA Scikit-adaptation `_

* `Sphinx-Gallery `_

* `SunPy `_

* `Tonic `_

* `TorchDR `_

* `TorchIO `_

.. projects_list_end

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:

.. code-block:: console

    $ 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:

.. code-block:: console

    $ pytest sphinx_gallery

How to cite

===========

.. citation-begin-content

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

deposit `_.

.. _documentation: https://sphinx-gallery.github.io/

.. citation-end-content