updated the markdown documentation

README.md

@@ -8,4 +8,28 @@
     1. [More detailed description of scientific approach and input variables reference](doc/method.md)
     1. [Validity range of the parameters](doc/parameters.md)
     1. [License, bug tracker, references, citations](doc/further.md)
-    1. [Source code description] - functions and classes, inheritance with examples - *this can be generated using tools like doxygen - here we can already include that in the yaml file (that is how it works on gitlab)*
+    1. [Source code description](doc/sphinxdoc.md) - 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](doc/input.md). The methods are described in [method](doc/method.md). Details on the input parameters are given in [parameters](doc/parameters.md). 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 sphinx on your system.
+
+If you want to run the test module manually, execute  
+`python -m unittest`  
+in the `src/` directory.
+
+## github actions
+
+This repository contains a github action in `./github/workflows/'. This will run unit tests and update the documentation upon push to the master branch. It will also run unit tests upon pull request.

doc/input.md

@@ -1 +1,16 @@
 Here goes a description of the input required for your program.
+
+# Program input
+
+The program options can be displayed by running
+`python ./src/main.py -h`  
+
+This will return the possible input options and type of parameters. 
+
+For example, to calculate the side length of a square with the same area as a circle of radius r, you would run  
+`python ./src/main.py square -r 4`  
+
+For the side length of a pentagon, you would provide  
+`python ./src/main.py square -r 4`  
+
+The program will then return the side length of the selected object.

doc/method.md

@@ -1 +1,22 @@
 Here goes a description of the scientific method and explanation of the keywords in terms of a method reference.
+
+This is to use latex-style equations in github markdown - unfortunatly it is not as nifty as i.e. jupyter:
+
+<img src="https://render.githubusercontent.com/render/math?math=e^{i \pi} = -1">
+
+# Methods
+
+The program uses three functions to calculate the desired values.
+
+## The area of a circle
+The area is calculated using 
+<img src="https://render.githubusercontent.com/render/math?math=A = \pi r^2">
+
+## The side length of a square
+The side length of a square with given area is calculated using 
+<img src="https://render.githubusercontent.com/render/math?math=a = \sqrt{A}">
+
+
+## The side length of a pentagon
+The side length of a pentagon with given area is calculated using 
+<img src="https://render.githubusercontent.com/render/math?math=a = \sqrt{\frac{4}{\sqrt{5(5+2*\sqrt{5})}} \cdot A}">

doc/parameters.md

@@ -1 +1,5 @@
 Here goes a description of the parameters and their validity range.
+
+* The input parameter `r` - the radius of the circle - can only be a real number larger or equal to zero.
+* The input string is restricted to `square` or `pentagon`, no other methods have been implemented so far.
+

doc/sphinxdoc.md

@@ -0,0 +1 @@
+- *this can be generated using tools like sphinx*

requirements.txt

@@ -0,0 +1 @@
+sphinx

setup.sh

@@ -0,0 +1 @@
+python -m pip install -r requirements.txt