============== 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
_ - Atomistic Cookbook
_ - auto-sklearn
_ - Biotite
_ - Cartopy
_ - FURY
_ - pyGIMLi
_ - HyperSpy
_ - kikuchipy
_ - Matplotlib
_ - MNE-Python
_ - napari
_ - Nestle
_ - NetworkX
_ - Neuraxle
_ - Nilearn
_ - OpenML
_ - OpenTURNS
_ - Optuna
_ - PlasmaPy
_ - POT
_ - pvlib
_ - PyGMT
_ - pyRiemann
_ - PyStruct
_ - PySurfer
_ - PyTorch tutorials
_ - PyVista
_ - pyxem
_ - RADIS
_ - scikit-image
_ - scikit-learn
_ - SimPEG
_ - SKADA Scikit-adaptation
_ - Sphinx-Gallery
_ - SunPy
_ - Tonic
_ - TorchDR
_ - 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:
.. 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