Developer Guide
Setting Up the Development Environment
This section provides instructions for setting up your development environment. If you follow the steps from top to bottom you should be ready to roll by the end.
Get the Source
The source code for the hifis-surveyval project lives at Gitlab. You can use git clone to get it. Chose one of the options.
# via ssh (recommended)
git clone git@gitlab.hzdr.de:hifis/overall/surveys/hifis-surveyval.git
# via https
git clone https://gitlab.hzdr.de/hifis/overall/surveys/hifis-surveyval.git
Create the Virtual Environment
The dependencies for this project are handles by Poetry. You need to install poetry first.
pip install poetry
Poetry also creates the virtual environment and installs the project’s dependencies.
poetry install
Try It Out
One way to test out the environment is to run the tests. You can do this with the make test target.
make test
If the tests run and pass, you’re ready to roll.
Make Changes to the Source Code
We use the GitLab Development Cycle. The short summary:
Create an issue
Create a merge request from the issue
Make your changes to the source code on the created branch
Run linter and test (see ‘Using the Makefile’)
Push your changes to GitLab
Run Changes
You can run the changed package in the local development environment without prior building.
poetry run hifis-surveyval <ARGS>
Using the Makefile
This project includes a Makefile that you can use to perform common tasks such as running tests and building documentation.
This section contains a brief description of the targets defined in the
Makefile
.
build
Uses poetry to generate a Python package.
clean
Remove generated packages, documentation, temporary files, etc.
coverage
Run the unit tests. It generates the coverage report to a HTML file to later be included in the documentation.
docs
Build the documentation for production.
After building the documentation, you can open it locally with $BROWSER
docs/build/html/index.html
.
Note
You can also build the documents directly, bypassing validations like linting and testing using Sphinx Makefile directly.
cd docs
make clean && make html
make latexpdf
lint
Run FlakeHell against the project files.
FlakeHell is a wrapper for Flake8 to
make it compatible to the pyproject.toml
, which we use.
package
Build the package for publishing. This includes the documentation.
reformat
Runs Sphinx Makefile an Sphinx Makefile to make the linter happy.
Note
You might need to format the docstrings manually to satisfy the linter as well as sphinx.
test
Run the unit tests. It generates the coverage report to the CLI.
Publishing
The software is published on PyPI. This is done via GitLab CI on tags, but only via a manual trigger in the end. There is no need to do it manually.
In case you need to do it manually anyway, please use poetry as shown below.
make package
poetry publish