Draft: Resolve "CI/CD exits with warnings with the default template."

Closes #3

README.md

@@ -13,8 +13,53 @@ To bootstrap a Python project, run:
 
     cookiecutter https://git.km3net.de/templates/python-project.git
 
-The default `LICENSE` is MIT, feel free to replace it with the one you like.
+and fill the required metadata. After filling the required metadata, a folder is created inside the working directory. The name of this folder depends on the metadata provided after running the `cookiecutter` command above. Here, we asume that this folder is named `project_dir`. This is folder is the base directory of the new python project.
 
+### Files and directories inside the python project
+`cookiecutter` uses the provided metadata to generate a set of files and directories inside the `project_dir` folder. These files are necessary to package and distribute python projects with (setuptools)[https://packaging.python.org/en/latest/key_projects/#setuptools]:
+
+#### LICENSE
+This file describes under which conditions the python project is or will be made available. The default `LICENSE` is MIT, feel free to replace it with the one you prefer. 
+
+### CHANGELOG.rst
+Open-source projects often include a changelog file as one of the top-level files in the base directory. The changelog file is a record of all the significant changes made to the project such as bug fixes or new features. There are ways of automating the changelog update based on the git commit messages. One can also edit the `CHANGELOG.rst` file manually and write the relevant changes there. 
+
+### CONTRIBUTING.rst
+This file contains guidelines for external users who would like to contribute to the project. 
+
+### setup.py
+This file is normally located in the base direcotry of a python project, and it is the most basic requirement for packaging a python project. It defines the configuration of the python project, and it is used by `setuptools` to ensure that this configuration is created at the time of building and using the package. The most important feature of this file is the call to a `setup()` function, to setup the environment. This can receive multiple arguments. In this template, the arguments used in the call to the `setup()` function are obtained from the metadata provided after running the `cookiecutter` command above. A list of the most relevant arguments and their description is given (here)[https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#setup-args]. This template includes the following arguments:
+- **name:** Name of the project
+- **url:** Url of the project
+- **description:** A short description of the project
+- **long_description:** A longer description of the project
+- **author:** Name of the author of the project
+- **author_email:** email-address of the author of the project
+- **packages:** list of packages and subpackages in the project. This list of packages will be made available from the python environment after installing it. By default, the `packages` argument includes a single package with the same name as the project name. A package is a folder which includes a file named `__init__.py` and some other source files. This default package is also generated by the `cookiecutter` (see below).
+- **include_package_data:** Set to `True` by default. It installs data files if these are specified in the `MANIFEST.in` file. See below. 
+- **platforms:** List of strings indicating what platforms is the project expected to be used from. The default value is set to `['any']`.
+- **setup_requires:** A string or list of strings specifying what other distributions need to be present in order for the setup script to run. See (here)[https://setuptools.pypa.io/en/latest/userguide/keywords.html]
+- **use_scm_version:** By default is set to true. If scm (source control management) version is used, then versions of the python software are tracked and assoiated to versions of the git repository. 
+- **python_requires:** Specifies required python versions. By default set to `>=3.6`
+- **install_requires:** Specifies list of dependencies for this project. These are installed by pip when typing `make` (see below). Instead of writing the list on the `setup.py` file, this template provides a file located on `<project_dir>/requirements/install.txt`. This file is parsed at install time and each of the depencencies defined within, are used as `install_requires` argument.
+- **extras_require:** The same as install_requires, but used when the code is built in developer mode. In this case, the dependencies are specified on the file `<project_dir>/requirements/install.txt`. 
+- **classifiers:** Specifies classifiers for the project. Read more about it (here)[https://pypi.org/classifiers/]
+
+### Makefile
+It declares the following recipes:
+- **install:** Installs the project.
+- **install-dev:** Installs the project in editable mode.
+- **clean:** 
+- **test:**
+- **test-cov:**
+- **test-loop:**
+- **flake8:**
+- **pep8:**
+- **docstyle:**
+- **lint:**
+- **dependencies:**
+- **black:**
+- **black-check:**
 
 ## Additional Setup