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/surveys/hifis-surveyval.git
# via https
git clone https://gitlab.hzdr.de/hifis/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.