Contributions & Development
How to contribute
We welcome community feedback and contributions! We are happy to have
- general feedback and questions on the image.sc forum,
- feature requests and bug reports as issues on GitHub,
- documentation, examples and code contributions as pull requests on GitHub.
The webknossos-libs repository is structured as a mono-repo, containing multiple packages:
docs, see below for Documentation)
See below for specifics of the different packages. Let's have a look at the common tooling first:
- poetry is used for dependency management and publishing.
By default, it creates a virtual environment for each package.
To run commands inside this package, prefix them with
poetry run, e.g.
poetry run python myscript.py, or enter the virtual environment with
poetry shell. The creation of a separate environment can be disabled (e.g. if you want to manage this manually), see here for details. To install the preferred version for this repository, run
pip install -f requirements.txt
To install the dependencies for all sub-projects, run
* Tooling we use across the sub-projects:
format.sh: black and isort
test.sh: pytest and custom scripts
Those are also accessible via make commands from the top-level directory, running the respective scripts for each sub-project
make lint, …
Internal workflows for scalable minds:
- CI: We use continuous integration with github actions,
please see the
CIworkflow for details.
- Releases are triggered via the
Automatic releasegithub action, using the
Run workflowbutton in the topright corner. This updates the changelog and pushes a new tag, which triggers another CI run building and publishing the package.
webknossos folder contains examples, which are not part of the package, but are tested via
tests/test_examples.py and added to the documentation (see
The tests also contain functionality for the webKnossos client. There a two modes to run the tests:
test.sh --refresh-snapshots, sending network requests to a webKnossos instance: This expects a local webKnossos setup with specific test data, which is shipped with webKnossos. If you're starting and running webKnossos manually, please use port 9000 (the default) and run the
tools/postgres/prepareTestDb.shscript in the webKnossos repository (⚠️ this overwrites your local webKnossos database). Alternatively, a docker-compose setup is started automatically for the tests, see
tests/docker-compose.ymlfor details. The network requests & response are recorded as "cassettes" by vcr.py, see next point:
test.shreplays responses from previous network snapshots using vcr.py via pytest-recording. No additional network requests are allowed in this mode.
The code under
webknossos/client/_generated is auto-generated! Please don't adapt anything in the
generated folder manually, but re-run the code generation.
To re-generate the code, run
Currently the test setup consists of different scripts as well as pytest tests. The following commands are run in CI:
tar -xzvf testdata/WT1_wkw.tar.gz poetry run pytest tests poetry run tests/scripts/all_tests.sh
There is also a
test.sh which is currently outdated, see issue #580.
For testing the
slurm setup a docker-compose setup is available. Please see the respective Readme for details.
For testing the
kubernetes setup, we recommend a Kubernetes-in-Docker setup.
We render a common documentation for webKnossos itself and webknossos-libs from this repository using mkdocs. Source-files for the documentation are stored at
docs/src/webknossos: Server & Website documentation, linked from the webknossos repository (must be available under
docs/wk-repo, see below).
docs/src/api: Generated using pdoc from Python docstrings.
docs/src/wkcuber: Documentation for the respective Python Packages
The structure of the documentation page is given by
To generate the documentation locally, clone or link the webKnossos repository to
docs/wk-repo first and then start the documentation server
git clone --depth 1 firstname.lastname@example.org:scalableminds/webknossos.git docs/wk-repo docs/generate.sh
You can use
docs/generate.shfor hot-reloading markdown docs,
docs/generate.sh --apito get the pure pdoc documentation, hot-reloading docstrings,
docs/generate.sh --persistto persist the docs under docs/out.