04_contributing.rst

Contributing to armscan_env

Install Develop Version

armscan_env is built and managed by poetry. For example, to install all relevant requirements in editable mode you can simply call

$ poetry install --with dev

PEP8 Code Style Check and Formatting

Please set up pre-commit by running

$ pre-commit install

in the main directory. This should make sure that your contribution is properly formatted before every commit.

The code is inspected and formatted by black and ruff. They are executed as pre-commit hooks. In addition, poe the poet tasks are configured. Simply run poe to see the available tasks. E.g, to format and check the linting manually you can run:

$ poe format
$ poe lint

Type Check

We use mypy to check the type annotations. To check, in the main directory, run:

$ poe type-check

Test Locally

This command will run automatic tests in the main directory

$ poe test

Documentation

Documentations are written under the docs/ directory as ReStructuredText (.rst) files. index.rst is the main page. A Tutorial on ReStructuredText can be found here.

API References are automatically generated by Sphinx according to the outlines under docs/api/ and should be modified when any code changes.

To compile documentation into webpage, run

$ poe doc-build

The generated webpage is in docs/_build and can be viewed with browser (http://0.0.0.0:8000/).

Documentation Generation Test

We have the following three documentation tests:

1. pydocstyle (as part of ruff): test all docstring under armscan_env/;
2. doc8 (as part of ruff): test ReStructuredText format;
3. sphinx spelling and test: test if there is any error/warning when generating front-end html documentation.

To check, in the main directory, run:

$ poe lint
$ poe doc-build