# 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 `pyproject.toml` and can be installed from those files:

    python -m pip install --editable ".[dev]"

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 in `sphinx_gallery/tests`.

#### tinybuild

`tinybuild` is designed as the minimal full sphinx doc build that you can run with `make html` from `tinybuild/doc` to get a traditional build experience.

`tinybuild` gets run in `tests/test_full.py` to build a test page using the `.rst` document files in `tests/doc/tinybuild`. The tests examine the `html` output to verify the behavior of the directives in the `.rst` files.