Sphinx-Gallery
0.10.1
Versions v: stable
Versions
dev
stable

Using Sphinx Gallery

  • Getting Started with Sphinx-Gallery
  • How to structure your Python scripts for Sphinx-Gallery
  • Configuration
  • Who uses Sphinx-Gallery

Advanced usage and information

  • Advanced usage
  • Frequently Asked Questions
  • Sphinx-Gallery Utilities

Example galleries

  • Gallery of Examples
  • Notebook style example

API and developer reference

  • Sphinx-Gallery API Reference
  • Change Log
  • Fork Sphinx-Gallery on Github
Sphinx-Gallery
  • Docs »
  • Welcome to Sphinx-Gallery’s documentation!

Welcome to Sphinx-Gallery’s documentation!¶

https://dev.azure.com/sphinx-gallery/sphinx-gallery/_apis/build/status/sphinx-gallery.sphinx-gallery?branchName=master https://circleci.com/gh/sphinx-gallery/sphinx-gallery.svg?style=shield

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

A demo of a gallery generated by Sphinx-Gallery

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
    • Plain RST examples
  • 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
    • Multi-resolution images
    • Image scrapers
    • Using multiple code blocks to create a single figure
    • Generating dummy images
    • Resetting modules
    • Order of 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
    • Resetting before each example
    • Altering Sphinx-Gallery CSS
    • 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.10.1
    • v0.10.0
    • v0.9.0
    • 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

Next

© Copyright 2014-2021, Sphinx-gallery developers.

Built with Sphinx using a theme provided by Read the Docs.