Overview your project files and folders#

This section describes the general files and structure needed for Sphinx-Galleryto build your examples.

Let’s say your Python project has the following structure:

.├── doc│   ├── conf.py│   ├── index.rst|   ├── make.bat│   └── Makefile├── my_python_module│   ├── __init__.py│   └── mod.py└── examples    ├── plot_example.py    ├── example.py    └── GALLERY_HEADER.rst (or README.[rst/.txt])

• doc is the Sphinx ‘source directory’. It contains the Sphinx baseconfiguration files. Default versions of these base files can obtained fromexecutingsphinx-quickstart (more details atSphinx-quickstart). Sphinx.rst source files are generally also placed here (none included inour example directory structure above) but these areunassociated with Sphinx-Gallery functions.

• my_python_module contains the.py files of your Python module. Thisdirectory is not required and Sphinx-Gallery can be used for a variety ofpurposes outside of documenting examples for a package, for examplecreating a website for a Python tutorial.

• examples contains the files used by Sphinx-Gallery to build the gallery.

Sphinx-Gallery expects theexamples directory to have a specific structure,which we’ll cover next.

Structure the examples folder#

In order for Sphinx-Gallery to build a gallery from yourexamples folder,this folder must have the following things:

• The gallery header: A file namedGALLERY_HEADER.[ext],where[ext] is ‘txt’ or an entry insphinx_gallery_conf["source_suffix"] (orfor backward-compatibilityREADME.[ext]). Default recommendation isGALLERY_HEADER.rst. This file should contain reST to be used as a header forthe gallery welcome page, which willalso include thumbnails generated from this folder. It must have at least atitle. For example:

  Thisismygallery==================Belowisagalleryofexamples

• Example Python scripts: A collection of Python scripts that will beprocessed when you build your HTML documentation. For information on howto structure these Python scripts with embedded reST, seeStructuring Python scripts for Sphinx-Gallery.

  • By defaultonly files prefixed withplot_ will be executed andtheir outputs captured to incorporate them in the HTMLoutput of the script. Files without that prefix will be only parsed andpresented in a rich literate programming fashion, without any output. Tochange the default file pattern for execution and capture seeParsing and executing examples via matching patterns.

  • The output that is captured while executing the.py files andsubsequently incorporated into the built documentation can be finelytuned. SeeControlling what output is captured.

  • You can have sub-directories in yourexamples directory. These will beincluded as sub-sections of your gallery. Theymust contain their ownGALLERY_HEADER.[ext] file as well. Note that[ext] can be ‘txt’ or anentry insphinx_gallery_conf["source_suffix"]. We also supportREADME.[ext] for backward-compatibility.

Configure and use Sphinx-Gallery#

After Sphinx-Gallery is installed, we must enable and configure it to buildwith Sphinx.

First, enable Sphinx-Gallery in the Sphinxdoc/conf.py file with:

extensions=[...'sphinx_gallery.gen_gallery',]

This loads Sphinx-Gallery as one of your extensions, the ellipsis... represents your other loaded extensions.

Next, create your configuration dictionary for Sphinx-Gallery. Here we willsimply set the minimal required configurations. We must set the location ofthe ‘examples’ directory (containing the gallery header file and our examplePython scripts) and thedirectory to place the output files generated. The path to both of thesedirectories should be relative to thedoc/conf.py file.

The following configuration declares the location of the ‘examples’ directory('example_dirs') to be../examples and the ‘output’ directory('gallery_dirs') to beauto_examples:

sphinx_gallery_conf={'examples_dirs':'../examples',# path to your example scripts'gallery_dirs':'auto_examples',# path to where to save gallery generated output}

After building your documentation,gallery_dirs will contain the followingfiles and directories:

• index.rst - the master document of the gallery containing the galleryheader, table of contents tree and thumbnails for each example. It will serveas the welcome page for that gallery.

• sg_execution_times.rst - execution time of all example.py files,summarised in table format (original pull request on GitHub).

• images - directory containing images produced during execution of theexample.py files (more details inImage scrapers) and thumbnailimages for the gallery.

• A directory for each sub-directory in'example_dirs'. Within eachdirectory will be the above and below listed files for that ‘sub-gallery’(aka subsection).

Additionally foreach.py file, a file with the following suffix isgenerated:

• .rst - the rendered reST version of the.py file, ready for Sphinxto build.

• .ipynb - to enable the user to download a Jupyter notebook version of theexample.

• .py - to enable the user to download a.py version of the example.

• .py.md5 - a md5 hash of the.py file, used to determine if changeshave been made to the file and thus if new output files need to be generated.

• .codeobj.json - used to identify function names and to which modulethey belong (more details inIdentifying function names in a script)

Additionally, two compressed.zip files containing all the.ipynb and.py files are generated, as well as a root-levelsg_execution_times.rst filecontaining all of the execution times.

For more advanced configuration, see theConfiguration page.

Add your gallery to the documentation#

Theindex.rst file generated for your gallery can be added to the table ofcontents tree in the main Sphinxdoc/index.rst file or embedded in aSphinx source.rst file with an..include:: statement.

Build the documentation#

In your Sphinx source directory, (e.g.,myproject/doc) execute:

$makehtml

This will start the build of your complete documentation. Boththe Sphinx-Gallery output files described above andthe Sphinx built HTML documentation willbe generated. Once a build is completed, all the outputs from your exampleswill be cached.In the future, only examples that have changed will be re-built.

You should now have a gallery built from your example scripts! For moreadvanced usage and configuration, check out theAdvanced usage page ortheConfiguration reference.