Template changes, changes to comment formatting

.deprecated_files

@@ -12,3 +12,5 @@
 
 scripts/check_mandatory_and_static_files.py
 scripts/update_static_files.py
+
+docs

.description.md

@@ -0,0 +1,25 @@
+<!-- Please provide a short overview of the features of this service.-->
+
+This repo is a template for creating a new microservice.
+
+The directories, files, and their structure herein are recommendations
+from the GHGA Dev Team.
+
+### Naming Conventions
+The github repository contains only lowercase letters, numbers, and hyphens "-",
+e.g.: `my-microservice`
+
+The python package (and thus the source repository) contains underscores "_"
+instead of hyphens, e.g.: `my_microservice`
+However, an abbreviated version is prefered as package name.
+
+### Adapt to your service
+This is just a template and needs some adaption to your specific use case.
+
+Please search for **"please adapt"** comments. They will indicate all locations
+that need modification. Once the adaptions are in place, please remove these #
+comments.
+
+Finally, follow the instructions to generate the README.md described in
+[`./readme_generation.md`](./readme_generation.md). Please also adapt this markdown file
+by providing an overview of the feature of the package.

.design.md

@@ -0,0 +1,7 @@
+<!-- Please provide an overview of the architecture and design of the code base.
+Mention anything that deviates from the standard triple hexagonal architecture and
+the corresponding structure. -->
+
+This is a Python-based service following the Triple Hexagonal Architecture pattern.
+It uses protocol/provider pairs and dependency injection mechanisms provided by the
+[hexkit](https://github.com/ghga-de/hexkit) library.

.github/workflows/check_readme.yaml

@@ -0,0 +1,16 @@
+name: Check if the readme is up to date.
+
+on: push
+
+jobs:
+  static-code-analysis:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - id: common
+        uses: ghga-de/gh-action-common@v2
+
+      - name: Check readme
+        run: |
+          ./scripts/update_readme.py --check

.gitignore

@@ -50,6 +50,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+prof/
 
 # Translations
 *.mo

.mandatory_files

@@ -10,11 +10,6 @@
 .devcontainer/docker-compose.yml
 .devcontainer/Dockerfile
 
-
-docs/README.md
-
-example_data
-
 tests/__init__.py
 tests/fixtures/__init__.py
 
@@ -28,3 +23,6 @@ README.md
 setup.py
 setup.cfg
 requirements-dev.txt
+
+.description.md
+.design.md

.readme_template.md

@@ -0,0 +1,109 @@
+
+[![tests](https://github.com/ghga-de/$name/actions/workflows/unit_and_int_tests.yaml/badge.svg)](https://github.com/ghga-de/$name/actions/workflows/unit_and_int_tests.yaml)
+[![Coverage Status](https://coveralls.io/repos/github/ghga-de/$name/badge.svg?branch=main)](https://coveralls.io/github/ghga-de/$name?branch=main)
+
+# $title
+
+$summary
+
+## Description
+
+$description
+
+## Installation
+We recommend using the provided Docker container.
+
+A pre-build version is available at [docker hub](https://hub.docker.com/repository/docker/ghga/$name):
+```bash
+docker pull ghga/$name:$version
+```
+
+Or you can build the container yourself from the [`./Dockerfile`](./Dockerfile):
+```bash
+# Execute in the repo's root dir:
+docker build -t ghga/$name:$version .
+```
+
+For production-ready deployment, we recommend using Kubernetes, however,
+for simple use cases, you could execute the service using docker
+on a single server:
+```bash
+# The entrypoint is preconfigured:
+docker run -p 8080:8080 ghga/$name:$version --help
+```
+
+If you prefer not to use containers, you may install the service from source:
+```bash
+# Execute in the repo's root dir:
+pip install .
+
+# To run the service:
+$shortname --help
+```
+
+## Configuration
+### Parameters
+
+The service requires the following configuration parameters:
+$config_description
+
+### Usage:
+
+A template YAML for configurating the service can be found at
+[`./example-config.yaml`](./example-config.yaml).
+Please adapt it, rename it to `.$shortname.yaml`, and place it into one of the following locations:
+- in the current working directory were you are execute the service (on unix: `./.$shortname.yaml`)
+- in your home directory (on unix: `~/.$shortname.yaml`)
+
+The config yaml will be automatically parsed by the service.
+
+**Important: If you are using containers, the locations refer to paths within the container.**
+
+All parameters mentioned in the [`./example-config.yaml`](./example-config.yaml)
+could also be set using environment variables or file secrets.
+
+For naming the environment variables, just prefix the parameter name with `${shortname}_`,
+e.g. for the `host` set an environment variable named `${shortname}_host`
+(you may use both upper or lower cases, however, it is standard to define all env
+variables in upper cases).
+
+To using file secrets please refer to the
+[corresponding section](https://pydantic-docs.helpmanual.io/usage/settings/#secret-support)
+of the pydantic documentation.
+
+$openapi_doc
+
+## Architecture and Design:
+$design_description
+
+## Development
+For setting up the development environment, we rely on the
+[devcontainer feature](https://code.visualstudio.com/docs/remote/containers) of vscode
+in combination with Docker Compose.
+
+To use it, you have to have Docker Compose as well as vscode with its "Remote - Containers"
+extension (`ms-vscode-remote.remote-containers`) installed.
+Then open this repository in vscode and run the command
+`Remote-Containers: Reopen in Container` from the vscode "Command Palette".
+
+This will give you a full-fledged, pre-configured development environment including:
+- infrastructural dependencies of the service (databases, etc.)
+- all relevant vscode extensions pre-installed
+- pre-configured linting and auto-formating
+- a pre-configured debugger
+- automatic license-header insertion
+
+Moreover, inside the devcontainer, a convenience commands `dev_install` is available.
+It installs the service with all development dependencies, installs pre-commit.
+
+The installation is performed automatically when you build the devcontainer. However,
+if you update dependencies in the [`./setup.cfg`](./setup.cfg) or the
+[`./requirements-dev.txt`](./requirements-dev.txt), please run it again.
+
+## License
+This repository is free to use and modify according to the
+[Apache 2.0 License](./LICENSE).
+
+## Readme Generation
+This readme is autogenerate, please see [`readme_generation.md`](./readme_generation.md)
+for details.

.static_files

@@ -20,13 +20,15 @@ scripts/get_package_name.py
 scripts/update_config_docs.py
 scripts/update_template_files.py
 scripts/update_openapi_docs.py
+scripts/update_readme.py
 scripts/README.md
 
 .github/workflows/check_config_docs.yaml
 .github/workflows/check_template_files.yaml
 .github/workflows/static_code_analysis.yaml
 .github/workflows/unit_and_int_tests.yaml
 .github/workflows/check_openapi_spec.yaml
+.github/workflows/check_readme.yaml
 .github/workflows/cd.yaml
 
 example_data/README.md
@@ -44,3 +46,6 @@ LICENSE
 requirements.txt
 requirements-dev-common.txt
 setup.py
+
+.readme_template.md
+readme_generation.md