Contributing

Welcome to the plothist project! We appreciate your interest in contributing to our codebase. This document outlines the steps to get started with development, including setting up your environment and running tests. If you have any questions or need assistance, feel free to reach out to the maintainers. We welcome contributions of all kinds, including bug fixes, new features, and documentation improvements.

Building from source

Follow the instructions in Install the development version to install the development version of plothist.

Setting up a development environment

Nox

The fastest way to start with development is to use nox.

Nox is an automation tool that helps manage and run development tasks such as testing and linting. It is especially useful for ensuring your code works across different Python versions and adheres to the project’s quality standards. Nox handles everything for you, including setting up a temporary virtual environment for each run.

To set up nox:

If you don’t have it already, install pipx by following the instructions on their website.
Install nox using pipx:
```
pipx install nox
```

To use nox, simply run:

nox

This will lint and test the project using multiple Python versions.

You can also run specific nox sessions:

# List all the defined sessions
nox -l
# Run the linter only
nox -s lint
# Run the tests only
nox -s tests
# Build the documentation and serve it locally (display the documentation in a web browser with live-reloading)
nox -s docs
# Build the documentation without serving it
nox -s docs --non-interactive
# Check for broken links in the documentation
nox -s docs -- -b linkcheck
# Run the tests with coverage (takes a while)
nox -s coverage
# Generate the example figures. Needed if you update any of the example scripts.
nox -s generate_examples_figures -- tests/test_examples_*.py

Linters and Formatters

plothist uses prek to manage linters and formatters.

The tools are listed in .pre-commit-config.yaml. Key among them is Ruff is used for linting and formatting, with its configuration in pyproject.toml.

Use nox -s lint to run the linters and formatters.

To install the hooks, run the following command (assuming you have installed plothist via uv following the instructions in Install the development version):

uv run prek install