A Sphinx extension that builds an HTML gallery of examples from any set of Python scripts.
Project description
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…
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
You can do a direct install via pip by using:
$ pip install sphinx-gallery
Add examples to your docs
Let’s assume simple scenario, you have a Python package with a directory structure like this:
├── 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:
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:
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:
$ 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:
$ pytest sphinx_gallery
How to cite
If you would like to cite Sphinx-Gallery you can do so using our Zenodo deposit.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx_gallery-0.18.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 54317366e77b182672797e5b46ab13cca9a27eafc3142c59dc4c211d4afe3420 |
|
MD5 | 9ea427fe9b76a5a578b2b280497cac42 |
|
BLAKE2b-256 | a3f38fd1ef84f318d404dcd713c54647e616d93396beb28db216e281ba86d728 |