Contribute#
We appreciate your help in improving this document and our library!
Please open an issue if this document is unclear or missing a step.
Development Workflow#
- If you are interested in contributing code or documentation, we strongly recommend
that you install a development version of sphinx-gallery in a development environment. If you are unfamiliar with the git/github workflow, please see Github’s guide to contributing to projects.
- This guide assumes familiarity with the Github workflow and focuses on aspects
specific to contributing to Sphinx-Gallery.
Get Latest Source#
You can get the latest development source from our Github repository.
git clone https://github.com/<your github user name>/sphinx-gallery
Create a Dedicated Environment#
- We strongly recommend that you create a virtual environment for developing
Sphinx Gallery to isolate it from other Python installations on your system.
Create a new virtual environment:
python -m venv <file folder location>
Activate the virtual environment using one of the following:
source <file folder location>/bin/activate # Linux/macOS
<file folder location>\Scripts\activate.bat # Windows cmd.exe
<file folder location>\Scripts\Activate.ps1
Install Dependencies#
- Most of the Sphinx Gallery dependencies are listed in
requirements.txt
and
dev-requirements.txt
and can be installed from those files:
python -m pip install -r requirements.txt -r dev-requirements.txt
- Sphinx Gallery requires graphviz for drawing API
entry graphs:
python -m pip install graphviz
- Sphinx Gallery requires that setuptools
is installed. It is usually packaged with python, but if necessary can be installed using
pip
:
python -m pip install setuptools
Install for Development#
- Editable installs means that the environment Python will always use the most
recently changed version of your code. To install Sphinx Gallery in editable mode, ensure you are in the sphinx-gallery directory
cd sphinx-gallery
Then install using the editable flag:
python -m pip install -e .
Verify install#
Check that you are all set by running the tests:
python -m pytest sphinx_gallery
And by building the docs:
cd doc
make html
Install pre-commit hooks#
- pre-commit hooks check for things like spelling and formatting in contributed
code and documentation. To set up pre-commit hooks:
python -m pip install pre-commit
pre-commit install
Guidelines#
Testing#
- All code contributions should be tested. We use the pytest
testing framework and
tinybuild
to build test pages. Tests can be found insphinx_gallery/tests
.
tinybuild#
tinybuild
is designed as the minimal full sphinx doc build that you can run withmake html
fromtinybuild/doc
to get a traditional build experience.tinybuild
gets run intests/test_full.py
to build a test page using the.rst
document files intests/doc/tinybuild
. The tests examine thehtml
output to verify the behavior of the directives in the.rst
files.