Contributing#

Contributions are welcome in many forms — bug fixes, new features, documentation improvements, and issue reports are all appreciated.

Contributing Code#

Development happens on GitHub. To contribute a code improvement, fork the repository on GitHub, clone your fork, and install with uv (recommended):

git clone https://github.com/<your-username>/scenex
cd scenex
uv sync
pre-commit install

Running tests#

Once you've made a change, please write a test showing that your change works! This repository uses pytest to run the scenex unit tests

uv run --exact --no-dev --group test pytest

There are a few optional test groups depending on which backends you want to exercise:

For example, the following will run scenex tests pertaining to the vispy backend, the qt app, and the scenex model code:

uv run --exact --no-dev --group test --extra vispy --extra pyqt6 --group testqt pytest

Code style#

Pre-commit hooks handle formatting and linting automatically on each commit. To run them manually:

uv run pre-commit run --all-files

Contributing Documentation#

Documentation is built with zensical (an mkdocs-based tool), sourced from the docs/ folder.

Regenerating example pages#

Before building or serving the docs, regenerate the example pages and screenshots:

uv run --exact --extra pygfx --extra wx --group docs python docs/gen_examples.py

Re-run this script whenever examples are added, removed, or their docstrings change.

Serving locally#

uv run --group docs python -m zensical serve

The docs will be available at http://127.0.0.1:8000 and will live-reload as you edit.

{
    "name": "zensical serve",
    "type": "debugpy",
    "request": "launch",
    "module": "zensical",
    "args": ["serve"],
    "python": "${workspaceFolder}/.venv/Scripts/python.exe",
    "cwd": "${workspaceFolder}",
    "console": "integratedTerminal",
    "justMyCode": false,
    "subProcess": true
}