Contributing Guide

We appreciate your help in improving this document and our library!

Please open an issue if you face any problems or have suggestions for improvements. We are always happy to help.

If you are interested in contributing code or documentation, we strongly recommend that you install a development version of myst-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 MyST-Sphinx-Gallery.

Get Latest Source Code

You can get the latest development source from our Github repository. Fork the repository and clone it to your local machine:

git clone https://github.com/<your github user name>/myst-sphinx-gallery

Create a Dedicated Environment

We strongly recommend that you create a virtual environment for developing MyST Sphinx Gallery to isolate it from other Python installations on your system.

Create a new virtual environment using venv:

python -m venv myst_gallery

Activate the environment:

source <file folder location>/bin/activate  # Linux/macOS
<file folder location>\Scripts\activate.bat  # Windows cmd.exe
<file folder location>\Scripts\Activate.ps1

or using conda:

conda create -n myst_gallery python=3.10

Activate the environment:

conda activate myst_gallery

Install Dependencies

Most of the MyST Sphinx Gallery dependencies are listed in pyproject.toml and can be installed from those files:

python -m pip install ".[dev]"

MyST 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 MyST Sphinx Gallery in editable mode, ensure you are in the sphinx-gallery directory

cd myst-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 myst-sphinx_gallery

And by building the docs:

cd docs
make html

After building the docs, you can view them by opening _build/html/index.html in your browser.

To clean up the build files and generated galleries, run:

make clean

Install ruff and pre-commit

To ensure that code contributions conform to style guide, we use the ruff tool to check for common mistakes and uniform code style. The pre-commit is used to run these checks automatically while committing code. To install ruff and pre-commit:

python -m pip install ruff pre-commit

To run ruff on all files in the repository:

ruff check .

To install pre-commit hooks, which will run all checks on all files before each commit, run:

pre-commit install

Testing

All code contributions should be tested. We use the pytest testing framework to build test pages. Tests can be found in myst_sphinx_gallery/tests.