Content of the source code documentation

1. Name and short description of the software, authors, date of initial development
2. Main features
3. Main requirements
4. Further information:
   1. Input examples and explanations, step-by-step tutorial
   2. More detailed description of scientific approach and input variables reference
   3. Validity range of the parameters
   4. License, bug tracker, references, citations
   5. Source code description - functions and classes, modules, variables

python-project-template

This is a template for your software project. The example code calculates the side length of a square or a pentagon, that contains the same area as a circle of given radius r.

Scientific Software Center, Heidelberg University, 12/2020

The code can compute side lengths of two geometric objects - of a square and a pentagon. You have to select either one, output of both objects is currently not implemented. For usage see input. The methods are described in method. Details on the input parameters are given in parameters. A detailed source code description is given through the sphinx documentation (here will be the link to the doc).

The program requires a working python environment with numpy installed. The documentation requires sphinx to be installed on your system.

For installation, run
source setup.sh

This will pip-install the requirements of the template (numpy, sphinx and extensions, and pytest) on your system.

If you want to run the test module manually, execute
python -m pytest
in the src/ directory.

The repository contains a configuration file for pre-commit hooks. To activate the hooks, run pre-commit install. This will then provide a check whenever you commit changes to the repository: In particular, the linter flake8 will check all Python source files and iPython notebooks, and black will reformat all Python source files and iPython notebooks to adhere to the PEP rules. If the files are reformatted, or flake8 still detects further issues, the commit will fail as the files are changed. You need to stage these changed files again using the git add command and the commit to the repository again. Committing these the second time should then work and you can then push to the remote.

github actions

This repository contains a github action in ./github/workflows/. This will run linting, unit tests and update the documentation upon push to the master branch and upon pull request. The action can also be run manually in the "Actions" tab on the github website.

Linting

The linter (in this case, flake8 will point out potential bugs, errors, styling issues, and suspicious code.

Testing

You should always test your code against a reference. In this template, we use pytest which is a popular option that is very versatile.

So far, only unit tests are included in the code template (that is, tests of a specific component of the software), but as you develop your software, you should also add integration tests that check the overall behaviour of your code.

In the github action, the tests are performed under ubuntu, windows and mac operating systems to ensure that the code runs in different environments. Also, two different python versions are tested right now, 3.8 and 3.9.

Source Code Documentation: Functions, modules, classes, ...

The documentation should be updated as you update your code. Include appropriate method descriptions in your code and sphinx will update the documentation html for your functions, classes, etc. The documentation is build using make html in the doc folder. On your local machine, you can navigate to doc/build/index.html and check the styling. If your code is in a public repository, you can push your sphinx documentation to Read the docs.