==============
Sphinx-Gallery
==============

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

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

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.4718153.svg
    :target: https://doi.org/10.5281/zenodo.4718153

.. tagline-begin-content

A `Sphinx <https://www.sphinx-doc.org/en/master/>`_ extension that builds an
HTML gallery of examples from any set of Python scripts.

.. tagline-end-content

.. image:: doc/_static/demo.png
   :width: 80%
   :alt: A demo of a gallery generated by Sphinx-Gallery

Who uses Sphinx-Gallery
=======================

An incomplete list:

.. projects_list_start

* `Apache TVM <https://tvm.apache.org/docs/tutorial/index.html>`_
* `Astropy <https://docs.astropy.org/en/stable/generated/examples/index.html>`_
* `Auto-sklearn <https://automl.github.io/auto-sklearn/master/examples/index.html>`_
* `Biotite <https://www.biotite-python.org/examples/gallery/index.html>`_
* `Cartopy <https://scitools.org.uk/cartopy/docs/latest/gallery/>`_
* `Fury <https://fury.gl/latest/auto_examples/index.html>`_
* `GIMLi <https://www.pygimli.org/_examples_auto/index.html>`_
* `Matplotlib <https://matplotlib.org/stable/index.html>`_:
* `MNE-python <https://mne.tools/stable/auto_examples/index.html>`_
* `Nestle <http://kylebarbary.com/nestle/examples/index.html>`_
* `NetworkX <https://networkx.org/documentation/stable/auto_examples/index.html>`_
* `Neuraxle <https://www.neuraxle.org/stable/examples/index.html>`_
* `Nilearn <https://nilearn.github.io/stable/auto_examples/index.html>`_
* `OpenML-Python <https://openml.github.io/openml-python/main/examples/index.html>`_
* `Optuna <https://optuna.readthedocs.io/en/stable/tutorial/index.html>`_
* `PlasmaPy <https://docs.plasmapy.org/en/latest/examples.html>`_
* `pyRiemann <https://pyriemann.readthedocs.io/en/latest/index.html>`_
* `PyStruct <https://pystruct.github.io/auto_examples/index.html>`_
* `PySurfer <https://pysurfer.github.io/>`_
* `PyTorch tutorials <https://pytorch.org/tutorials>`_
* `PyVista <https://docs.pyvista.org/examples/>`_
* `Radis <https://radis.readthedocs.io/en/latest/auto_examples/index.html>`_
* `scikit-image <https://scikit-image.org/docs/dev/auto_examples/>`_
* `Scikit-learn <http://scikit-learn.org/stable/auto_examples/index.html>`_
* `SimPEG <https://docs.simpeg.xyz/content/examples/>`_
* `Sphinx-Gallery <https://sphinx-gallery.github.io/stable/auto_examples/index.html>`_
* `SunPy <https://docs.sunpy.org/en/stable/generated/gallery/index.html>`_
* `Tonic <https://tonic.readthedocs.io/en/latest/auto_examples/index.html>`_
* `TorchIO <https://torchio.readthedocs.io/auto_examples/index.html>`_

.. projects_list_end

Installation
============

Install via ``pip``
-------------------

.. installation-begin-content

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

.. code-block:: bash

    $ pip install sphinx-gallery

Sphinx-Gallery will not manage its dependencies when installing, thus
you are required to install them manually. Our minimal dependency
is **Sphinx >= 4**.

Sphinx-Gallery has also support for scraping images from packages like
Matplotlib, Seaborn, and Mayavi. For much of this functionality, you will need
``pillow``. We also recommend installing system ``optipng`` binaries to reduce
the file sizes of the generated PNG files.

.. installation-end-content

Contributing
============

You can get the latest development source from our `Github repository
<https://github.com/sphinx-gallery/sphinx-gallery>`_. 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
    $ 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:

.. 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 <https://zenodo.org/record/3838216>`_.

.. citation-end-content
