Create documentation about available tooling

.markdownlint.yml

@@ -0,0 +1,14 @@
+# For further information on the warnings visit
+# https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md
+
+default: true
+
+# Allow some exceptions for inline HTML
+MD033:
+  allowed_elements: ['picture', 'source', 'img']
+
+# Disables need for first line to be a big heading
+MD041: false
+
+# Disable line length warnings
+MD013: false

.vscode/extensions.json

@@ -1,6 +1,7 @@
 {
     "recommendations": [
         "ms-python.python",
-        "ms-python.black-formatter"
+        "ms-python.black-formatter",
+        "DavidAnson.vscode-markdownlint"
     ]
 }

CONTRIBUTING.md

@@ -20,10 +20,10 @@ besides a technical review:
 - **Python coding guidelines**: Make sure to follow the coding schema of the project.
 - **Ankaios SDK API alignment**: Keep in mind how the APIs of the other Ankaios SDKs would look like as all SDKs shall target similar API semantics.
 
-If a version change is required in the PR, use the [update_version.sh](./tools/update_version.sh) script to update the version.
+For information about development tools, workflows, and project setup, see the [Development Guide](DEVELOPMENT.md).
 
 ## Communication
 
 Please join our [developer mailing list](https://accounts.eclipse.org/mailing-list/ankaios-dev) for up to date information or use the Ankaios [discussion forum](https://github.com/eclipse-ankaios/ankaios/discussions).
-If you are looking for the main project, you can find it [here](https://github.com/eclipse-ankaios/ankaios/tree/main).
+If you are looking for the main project, you can find it [here](https://github.com/eclipse-ankaios/ankaios/tree/main).<!-- markdownlint-disable MD059 -->
 You can also join the conversion with the community in the [Ankaios Slack workspace](https://github.com/eclipse-ankaios/ankaios/wiki#slack).

DEVELOPMENT.md

@@ -0,0 +1,38 @@
+# Development Guide
+
+This guide provides information about the development tools and workflows available for this project.
+
+## Quick Start
+
+### Project Setup
+
+Install the SDK in development mode with the dev dependencies:
+
+```shell
+pip install -e ".[dev]"
+```
+
+## Commands and Scripts
+
+The project provides a unified check runner ([run_checks.py](./run_checks.py)) for common development workflows. For a complete list of the available checks and actions, run `python3 run_checks.py --help`.
+
+In addition, the [tools](tools/) folder contains helper scripts for specific tasks. Check the tools [readme](tools/README.md) for more info.
+
+## Updating Documentation
+
+When making changes to project documentation, keep the following in mind:
+
+**Documentation custom handling:**
+
+There are markdown files which are part of the published documentation. Because the links do not work directly, a [custom code](docs/source/conf.py) replaces them with the correct linkage.
+
+## Troubleshooting
+
+### Tests fail with strange errors regarding the protobuf objects
+
+If this is the case, the proto files do not match the local code. The fetching of the proto files is documented in the [setup.py](setup.py) script, in the `extract_the_proto_files` method. It might be the case that the proto files must be fetched again.
+
+## Additional Resources
+
+- [Contributing Guidelines](CONTRIBUTING.md)
+- [Python Coding Guidelines](https://peps.python.org/pep-0008/)

README.md

@@ -56,12 +56,12 @@ pip install -e ".[dev]"
 Please make sure the Python SDK is compatible with the version of Ankaios you
 are using. For information regarding versioning, please refer to this table:
 
-| Ankaios    | Python SDK |
-| -------- | ------- |
+| Ankaios         | Python SDK                                      |
+| --------------- | ----------------------------------------------- |
 | 0.4.x and below | No Python SDK available. Please update Ankaios. |
-| 0.5.x | 0.5.x     |
-| 0.6.x | 0.6.x     |
-| 0.7.x | 0.7.x     |
+| 0.5.x           | 0.5.x                                           |
+| 0.6.x           | 0.6.x                                           |
+| 0.7.x           | 0.7.x                                           |
 
 ## Usage
 
@@ -134,6 +134,7 @@ with Ankaios() as ankaios:
 ```
 
 For more details, please visit:
+
 * [Ankaios documentation](https://eclipse-ankaios.github.io/ankaios/latest/)
 * [Python SDK documentation](https://eclipse-ankaios.github.io/ank-sdk-python/)
 

docs/source/conf.py

@@ -65,11 +65,14 @@
         contrib[i] = line.replace(
             "./CODE_OF_CONDUCT.md", "./code_of_conduct.html"
         )
-        break
+    if "./DEVELOPMENT.md" in line:
+        contrib[i] = line.replace(
+            "./DEVELOPMENT.md",
+            "https://github.com/eclipse-ankaios/ank-sdk-python/blob/main/DEVELOPMENT.md",
+        )
 with open(contrib_out, "w") as f:
     f.writelines(contrib)
 
-
 # -- Prepare the Code of Conduct file - foot note warning -----------------------------------------
 coc_in = os.path.abspath(os.path.join(ROOT_DIR, "CODE_OF_CONDUCT.md"))
 coc_out = os.path.abspath(os.path.join(BUILD_DIR, "CODE_OF_CONDUCT.md"))

examples/README.md

@@ -9,7 +9,7 @@ In order to run the examples, Ankaios must be installed and available on the sys
 Alternatively you can compile from source and provide the path to the executables to the run scripts with the `ANK_BIN_DIR` environment variable.
 
 > **IMPORTANT**  
-> Make sure that no other Ankaios instance is running on the local machine. If there is an instance running, the example could change its configuration. The stop script would even stop all running instances and **delete all podman containers**. 
+> Make sure that no other Ankaios instance is running on the local machine. If there is an instance running, the example could change its configuration. The stop script would even stop all running instances and **delete all podman containers**.
 
 ## Building and running
 
@@ -42,13 +42,13 @@ To stop the example just call
 ```
 
 > **WARNING**  
-> The stop script terminates all running ankaios instances, both server and agents and **delete all podman containers** on the system. If you don't want this, you would need to clean up manually. 
+> The stop script terminates all running ankaios instances, both server and agents and **delete all podman containers** on the system. If you don't want this, you would need to clean up manually.
 
 ## Examples
 
 This folder currently contains three examples:
 
-### `hello_ankaios` 
+### `hello_ankaios`
 
 This example executes a workload that runs the example script from the main [README](../README.md#usage) of this repo.
 
@@ -60,13 +60,13 @@ To view the logs of an example like the `hello_ankaios` workload just use the co
  ./ank-logs.sh
 ```
 
-### `sleepy` 
+### `sleepy`
 
-`sleepy` is an "empty" workload that just executes an endless sleep. 
+`sleepy` is an "empty" workload that just executes an endless sleep.
 
 This example has the Python SDK installed and allows to execute an interactive shell in the container in order to manually trigger Python commands to interact with Ankaios.
 
-### `follow_state` 
+### `follow_state`
 
 `follow_state` executes indefinitely with a request to get the state being sent every 5 seconds.
 

tools/README.md

@@ -0,0 +1,21 @@
+# Helper Scripts
+
+This directory contains utility scripts for specific tasks. All scripts support the `--help` flag for detailed usage information.
+
+## fetch_protos.sh
+
+This script is used to fetch the proto files from a specific branch.
+
+## generate_docs.sh
+
+Generates project documentation using Sphinx. Creates a temporary virtual environment, installs documentation dependencies, builds the HTML docs, and cleans up.
+
+Output is saved to `docs/build`.
+
+## update_version.sh
+
+Updates SDK, Ankaios, and API versions across the project. Supports updating versions individually or all at once.
+
+## install_ankaios.sh
+
+This script provides multiple ways to install ankaios, from an official release to the executables generated by a github action of a specific branch. Use the `--help` for more details.

tools/fetch_protos.sh

@@ -1,14 +1,29 @@
 #!/bin/bash
 set -e
 
-# Script to fetch the proto files from the Ankaios repository
-# Usage: ./fetch_protos.sh <branch> [-v|--version <sdk_version>]
+usage() {
+    echo "Usage: $0 <branch> [-v|--version <sdk_version>] [--help]"
+    echo "Fetch the proto files from the Ankaios repository."
+    echo ""
+    echo "  <branch>                   The branch to fetch the proto files from."
+    echo "  -v / --version <version>   The SDK version to use for the proto directory."
+    echo "                             If not provided, the version is read from setup.cfg."
+    echo "  -h / --help                Display this help message and exit."
+    echo ""
+    echo "Example:"
+    echo "  $0 main"
+    echo "  $0 main --version 0.2.0"
+    exit 0
+}
 
 # Parse arguments
 if [ $# -lt 1 ]; then
     echo "Error: Missing required argument <branch>" >&2
-    echo "Usage: $0 <branch> [-v|--version <sdk_version>]" >&2
-    exit 1
+    usage
+fi
+
+if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+    usage
 fi
 
 BRANCH="$1"
@@ -26,10 +41,12 @@ while [ $# -gt 0 ]; do
             SDK_VERSION="$2"
             shift 2
             ;;
+        --help|-h)
+            usage
+            ;;
         *)
             echo "Error: Unknown argument: $1" >&2
-            echo "Usage: $0 <branch> [-v|--version <sdk_version>]" >&2
-            exit 1
+            usage
             ;;
     esac
 done

tools/generate_docs.sh

@@ -1,9 +1,41 @@
 #!/bin/bash
+
+# Copyright (c) 2025 Elektrobit Automotive GmbH
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License, Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
 set -e
 
 script_dir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 base_dir="$script_dir/.."
 
+usage() {
+    echo "Usage: $0 [--help]"
+    echo ""
+    echo "Generate project documentation using Sphinx."
+    echo "Creates a temporary virtual environment, installs documentation"
+    echo "dependencies, builds the HTML docs, and cleans up."
+    echo ""
+    echo "Output is saved to docs/build."
+    echo ""
+    echo "  --help    Display this help message and exit."
+    exit 0
+}
+
+if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+    usage
+fi
+
 python3 -m venv docs_env
 source docs_env/bin/activate