# Welcome to Sphinx-Gallery’s documentation!

`Sphinx-Gallery` is a Sphinx extension that builds an HTML gallery of examples from any set of Python scripts.

The code of the project is on Github: Sphinx-Gallery

## Features of Sphinx-Gallery

- Creating a basic Gallery by automatically running Python files, capturing outputs + figures, and rendering them into rST files ready for Sphinx when you build the documentation. Learn how to Overview your project files and folders

- Embed rST in your example Python files, allowing you to interweave narrative-like content with code that generates plots in your documentation. Sphinx-Gallery also automatically generates a Jupyter Notebook for each your example page.

- Add mini-galleries for API documentation. Sphinx-Gallery can generate mini-galleries listing all examples that use a particular function/method/etc.

- Add intersphinx links to your examples. Sphinx-Gallery can automatically add links to API documentation for functions/methods/classes that are used in your examples (for any Python module that uses intersphinx).

- Manage multiple galleries to create and embed galleries for several folders of examples.

## Installation

### Install via `pip`

You can do a direct install via pip by using:

    $ 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 >= 1.8.3

Sphinx-Gallery has also support for packages like:

- Matplotlib

- Seaborn

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

### Install as a Sphinx-Gallery developer

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 dev-requirements.txt
    $ pip install -e .

### Citation

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

### Sphinx-Gallery Show: Gallery of Examples

Using Sphinx Gallery

- Getting Started with Sphinx-Gallery
  - Creating a basic Gallery
- How to structure your Python scripts for Sphinx-Gallery
  - A simple example
  - Embed rST in your example Python files
- Configuration
  - List of config options
  - Removing warnings
  - Manage multiple galleries
  - Parsing and executing examples via matching patterns
  - Rerunning stale examples
  - Passing command line arguments to example scripts
  - Sorting gallery subsections
  - Sorting gallery examples
  - Add intersphinx links to your examples
  - Add mini-galleries for API documentation
  - Using a custom default thumbnail
  - Adding line numbers to examples
  - Removing config comments
  - Add your own first and last notebook cell
  - Adding images to notebooks
  - Using pypandoc to convert rST to markdown
  - Using JUnit XML files
  - Setting log level
  - Disabling download button of all scripts
  - Choosing the thumbnail image
  - Providing an image for the thumbnail image
  - Generate Binder links for gallery notebooks (experimental)
  - Building without executing examples
  - Compressing images
  - Image scrapers
  - Resetting modules
  - Dealing with failing Gallery example scripts
  - Setting gallery thumbnail size
  - Minimal reported time
  - Showing memory consumption
  - Show signature
  - Controlling what output is captured
- Who uses Sphinx-Gallery

Advanced usage and information

- Advanced usage
  - Extend your Makefile for Sphinx-Gallery
  - Know your Gallery files
  - Understanding warning and error outputs
  - Write a custom image scraper
  - Define resetting behavior (e.g., for custom libraries)
  - Using (only) Sphinx-Gallery styles
- Frequently Asked Questions
  - Why is __file__ not defined? What can I use?
  - Why am I getting text output for Matplotlib functions?
- Sphinx-Gallery Utilities
  - Convert Python scripts into Jupyter Notebooks
  - Embedding Sphinx-Gallery inside your documentation script extensions

Example galleries

- Gallery of Examples
  - General examples
  - No image output examples
- Notebook style example

API and developer reference

- Sphinx-Gallery API Reference
  - Sphinx Gallery
  - sphinx_gallery.gen_gallery
  - sphinx_gallery.backreferences
  - sphinx_gallery.gen_rst
  - sphinx_gallery.scrapers
  - sphinx_gallery.py_source_parser
  - sphinx_gallery.docs_resolv
  - sphinx_gallery.notebook
  - sphinx_gallery.downloads
  - sphinx_gallery.sorting
  - sphinx_gallery.binder
  - sphinx_gallery.directives
  - Utilities
  - sphinx_gallery.utils.optipng
- Change Log
  - v0.8.2
  - v0.8.1
  - v0.8.0
  - v0.7.0
  - v0.6.2
  - v0.6.1
  - v0.6.0
  - v0.5.0
  - v0.4.0
  - v0.3.1
  - v0.3.0
  - v0.2.0
  - v0.1.13
  - v0.1.12
  - v0.1.11
  - v0.1.10
  - v0.1.9
  - v0.1.8
  - v0.1.7
  - v0.1.6
  - v0.1.5
  - v0.1.4
  - v0.1.3
  - v0.1.2
  - v0.1.1
  - v0.1.0
  - v0.0.11
  - v0.0.10
- Fork Sphinx-Gallery on Github

## Indices and tables

- Index

- Module Index

- Search Page