Code contributions

This documentation is for those interested in helping in the development/improvement of pyRSKtools. If you are only looking to use pyRSKtools as a library, please see the standard installation instructions.

Development of pyRSKtools requires the use of Git for source code version control. The official remote public repository for pyRSKtools is hosted on Bitbucket at https://bitbucket.org/rbr/pyrsktools.

Setting up a development environment

The steps below outline how to set up a basic development environment from a UNIX-like command line interface (CLI).

  1. Cloning pyRSKtools:

git clone https://bitbucket.org/rbr/pyrsktools.git

  1. Setting up a virtual environment:

cd pyrsktools
python -m venv env
source env/bin/activate

  1. Installing pyRSKtools’ standard and development dependencies:

pip install -e .[dev]

You may now freely edit and import/run pyRSKtools to your liking. For information on style guidelines and running tests, see below.

Style guidelines

pyRSKtools uses Black and mypy to ensure code remains consistent in style and type hinting. Style and type hinting are enforced over code pushed to Bitbucket (see bitbucket-pipelines.yml). It is highly recommended you run these tools against any changes you make before pushing them.

If you have already setup your development environment, you may:

Run black against the entire code base with:

black --check pyrsktools

Run mypy using pyRSKtools’ custom configuration with:

mypy --config mypy.ini pyrsktools

Running tests

Tests are located in the tests directory at the base of the repository. Assuming you have already setup your development environment, you may run all tests with:

python -m unittest discover tests

See the official Python unittest documentation for more information.

Documentation contributions

The full source code for this documentation is located at the base of the repository in the docs directory. All documentation is built and generated using Sphinx.

Viewing/compiling locally

To generate the HTML you are viewing currently, you may use the provided Makefile in the docs directory:

make html

This command will create the build directory in docs, the generated HTML will be stored in build/html. To view the documentation, you may open build/html/index.html with your browser directly or, alternatively, you may run the make command below:

make serve

This will generate the HTML documentation and serve it locally on port 8000. Type http://0.0.0.0:8000 in your browser to access it.