Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
92 lines (60 loc) · 3.12 KB

CONTRIBUTING.md

File metadata and controls

92 lines (60 loc) · 3.12 KB
Raw

Contributing guide

Thanks for your interest in contributing to waveorder!

Please see the following steps for our workflow.

Getting started

Please read the README for an overview of the project, and how you can install and use the package.

Issues

We use issues to track bug reports, feature requests, and provide user support.

Before opening a new issue, please first search existing issues (including closed ones), to see if there is an existing discussion about it.

Setting up development environment

Install Git and uv.

If you have push permission to the repository, clone the repository (the code blocks below are shell commands):

cd # to the directory you want to work in
git clone https://github.com/mehta-lab/waveorder.git

Otherwise, you can follow these instructions to fork the repository.

Next, create a virtual environment and install the package with all dev dependencies:

cd waveorder/
uv sync --group dev --extra visual

Check that the tests pass:

uv run pytest

Finally, make the changes and track them with Git.

Dependency groups:

  • --group test — pytest, hypothesis, napari test deps
  • --group docs — sphinx and documentation deps
  • --group dev — includes both test and docs
  • --extra visual — napari, PyQt6, and visualization deps

Code style

We use pre-commit to lint with ruff automatically prior to each commit. Install pre-commit in your environment:

pre-commit install

To manually check formatting and linting:

uvx ruff check .
uvx ruff format --check .

Developing documentation

Documentation infrastructure is built using Markdown (.md) and reStructuredText (.rst) files. Sphinx utilizes these to build highly customization .html pages for User Guides, API References and Examples rendered directly from source code files.

Building the HTML version locally

cd waveorder/
uv sync --group docs
cd docs/
uv run sphinx-build -M html ./ ./build

Generated HTML documentation can be found in the build/html directory. Open build/html/index.html to view the home page for the documentation.

Automated building of docs is done via read-the-docs which will automatically pull commits to the main branch and host them here: https://waveorder.readthedocs.io

Documentation change

If you find that any documentation in this project is incomplete, inaccurate, or ambiguous, please open an issue. We welcome contributions to the documentation from users, particularly user guides that we can collaboratively edit.