Developer Guide

Contributing

Contributions are welcome. Areas that need work include:

  • Code quality and refactoring

  • Documentation and docstrings

  • Unit tests (test_*.py) and visual tests (visual_test_*.py)

  • New features and bug fixes

Code conventions

  • Use Python 3-compatible code:

    print("use print as a function")

  • Follow PEP 8 where applicable: https://pep8.org/

  • Write tests for new or changed behaviour.

Running tests

Tests use pytest. Install test deps: pip install -e ".[test]" or use the pixi environment. From the project root:

  • Unit tests only (default; excludes visual/GUI tests; use for CI):

    pytest tests/ -m "not visual"
./testall.py
pixi run test

  • All tests (including visual_test_*.py; needs display/VTK):

    pytest tests/
./testall.py -a
pixi run test-all

  • Single file or filter: pytest tests/test_glider.py -v, pytest tests/ -k "glider" -v, ./testall.py -p "glider".

Visual tests are marked with the visual marker (see pyproject.toml and tests/conftest.py). Full details: tests/README.md in the repository.

Building documentation

From the project root (with pixi or pip install sphinx):

pixi run docs
# or:  sphinx-build -b html docs/source docs/build/html

Output is in docs/build/html/. From the docs/ directory you can also use make apidoc (regenerate API .rst) and make html. Use sphinx-build -W for strict warnings (e.g. in CI).

API documentation

The API docs are generated from the source with sphinx-apidoc. To improve the generated docs:

  • Add module and class docstrings.

  • Use Google- or NumPy-style docstrings so sphinx.ext.napoleon can parse them.

See the API Reference for the current API reference.