Welcome to the developer documentation of the cwepr package. Unlike the API documentation, this part gives some general background information for developers who want to actively contribute to the project.
The whole development should take place inside a virtual python environment that should be located outside the project directory.
To create a new virtual python environment, open a terminal and change to a a directory where the virtual environment should reside. Then type something like:
python3 -m venv cwepr
This will create a virtual environment in the directory “cwepr”. To activate this virtual environment, use:
To deactivate, the command would simply be:
Autoincrementing version numbers
The version number is contained in the file
VERSION in the project root directory. To automatically increment the version number with every commit, use a git hook that calls the file
bin/incrementVersion.sh. Git hooks reside in the directory
.git/hooks. The simplest would be to create a new file
pre-commit in this directory with the following content:
#!/bin/sh bash bin/incrementVersion.sh
Make sure to set it to executable and have a line break (aka: new or empty line) at the end of the file. Otherwise, you man run into trouble, i.e., not having your version number updated automatically with each commit.
The cwepr package follows good practice of the Python community regarding directory layout. As there will be several subpackages available, these reside each in a separate directory containing its own
__init__.py file. All packages/modules reside below the
cwepr directory of the project root. The
tests directory follows the same structure and contains all the module tests. Generally, the cwepr package should be developed test-driven (test-first) as much as possible.
(This) documentation resides inside the
docs directory of the project root. The auto-generated API documentation is in its own directory.
A general overview of the overall package structure:
bin/ docs/ api/ cwepr/ io/ tests/
As you can see, currently there exists one subpackage, namely “io”, but others will soon be created as well. For details of the cwepr package as such, consult its Homepage.
The Docstring format used within the code of the cwepr package is “NumPy”. For convenience, set your IDE accordingly.
For PyCharm, the settings can be found in
Python Integrated Tools. Here, you find a section “Docstrings” where you can select the Docstring format from a number of different formats.
Unittests and test driven development
Developing the cwepr package code should be done test-driven wherever possible. The tests reside in the
tests directory in the respective subpackage directory (see above).
Tests should be written using the Python
unittest framework. Make sure that tests are independent of the respective local environment and clean up afterwards (using appropriate
Setting up the documentation build system
To install the necessary Python dependencies, create a virtual environment, e.g., with
virtualenv <environment>, and activate it afterwards with
<environment>/bin/activate. Then install the dependencies using
pip install sphinx pip install sphinx-rtd-theme sphinxcontrib-bibtex sphinx-multiversion
To build the documentation:
Activate the virtual environment where the necessary dependencies are installed in.
docs/, then run
make html. (To clean previously built documentation, run
Static code analysis with Prospector
Static code analysis can be performed using Prospector. First, install the necessary tools into the virtual environment created for the cwepr package:
pip install prospector[all] pip install prospector[with_pyroma]
Some shells (such as Zsh, the default shell of macOS Catalina) require brackets to be escaped:
pip install prospector\[with_pyroma\]
The optional arguments ensure that all necessary dependencies are installed as well.
Afterwards, simply run Prospector from a terminal from within your project root:
It will display the results of the static code analysis within the terminal. Settings can be changed in the
.prospector.yaml file in the project root, but please be very careful changing settings here. Often, it is better to (temporarily) silence warnings in the code itself.
For better readability, the prospector output can get printed into a file. The text output is the most human-readable in my opinion.
prospector -o text:prospector-out.txt