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).
Cloning pyRSKtools:
git clone https://bitbucket.org/rbr/pyrsktools.git
Setting up a virtual environment:
cd pyrsktools
python -m venv env
source env/bin/activate
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.