Contributions are very welcome. Please ensure all of your contributions are made via a pull request from a fork.
The recommended development environment is through poetry. If you prefer to
use something else that is fine, but beware it could lead to different environment
behaviour. The poetry.lock
file under version control should ensure you are
set up with the same environment as anyone else contributing to the library. Most
of the standard development tasks are managed through a Makefile
. The
Makefile
assumes that you are using poetry
.
After cloning your fork locally and entering the project directory, you can set up the poetry environment with
make install
All code is formatted with black
and isort
.
make fmt
flake8
handles linting. Please ensure there are no warnings before pushing any
work.
make lint
To test both the code and documentation, run
make test
All unit tests are contained in the tests
directory. If you add any code, please
ensure it is tested. Tests are handled by pytest
. To test just the code, without the
also testing the documentation, run
make test-code
The document testing is orchestrated by scripts/mdpydoctest
. This
script will extract all markdown python code blocks from docstrings in python files and
write a test file with a unit test for each snippet. It then runs pytest
on this file
to ensure all code examples in the docstrings are correct. To test the docs, run
make test-docs
Please keep the project's code coverage as high as possible. To check the code coverage, run
make coverage
This should show the coverage on the terminal and also open an HTML report in your web browser.
The code is documented using markdown docstrings. The convention this project follows is
akin to that used by the Rust programming language. The beginning of the docstring
should explain what the function does and if it returns anything. This is followed,
where relevant, by an example section ## Example
. All examples should be valid,
self-contained examples that can be copied and pasted into a python shell and executed
successfully (assuming the user has pafpy
installed). These code snippets must be in a
code block annotated as py
or python
. See the code for examples. If the code being
documented can raise an exception, the type(s) of errors should be documented in an
## Errors
section also.
The documentation can be served locally in a browser so that you can view changes in realtime by running
make serve-docs
and then navigating to the URL printed in the terminal (most likely http://localhost:8080).
The docs can also be built by running
make docs
Then open docs/index.html
to view the documentation that will be deployed on pushing to master
.
There is a convenience rule in the Makefile
that can be run prior to committing that
will run most of the above tasks for you
make precommit