From d15a8461c5e2c6db41060f916a40b217c373ec2a Mon Sep 17 00:00:00 2001
From: Dr Yann Golanski <codeberg@kierun.org>
Date: Sun, 24 Aug 2025 19:41:28 +0100
Subject: [PATCH] docs(Python): more documentation

---
 Python/.woodpecker/docs.yaml     |  5 ++++-
 Python/.woodpecker/lint.yaml     |  2 ++
 Python/.woodpecker/mypy.yaml     |  5 ++++-
 Python/.woodpecker/security.yaml |  2 ++
 Python/.woodpecker/test.yaml     | 12 ++++++++++++
 5 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/Python/.woodpecker/docs.yaml b/Python/.woodpecker/docs.yaml
index 1f2a562..1acebfa 100644
--- a/Python/.woodpecker/docs.yaml
+++ b/Python/.woodpecker/docs.yaml
@@ -1,5 +1,8 @@
-# Checks documentaton with pydocstyle and then builds it. 
+# Checks documentaton with pydocstyle and then builds it.
+#
 # Note that it does not publish it, just checks you can build it.
+#
+# See test.yaml for more information.
 
 when:
   - event: pull_request
diff --git a/Python/.woodpecker/lint.yaml b/Python/.woodpecker/lint.yaml
index 5a78bd9..6c1b971 100644
--- a/Python/.woodpecker/lint.yaml
+++ b/Python/.woodpecker/lint.yaml
@@ -1,4 +1,6 @@
 # Simple linting with the latest version of ruff.
+#
+# See test.yaml for more information.
 
 when:
   - event: pull_request
diff --git a/Python/.woodpecker/mypy.yaml b/Python/.woodpecker/mypy.yaml
index 52e53c9..54e9c90 100644
--- a/Python/.woodpecker/mypy.yaml
+++ b/Python/.woodpecker/mypy.yaml
@@ -1,5 +1,6 @@
 # Check type hints wiht mypy.
-# Note that this uses uv to generate a requirements.txt file.
+#
+# See test.yaml for more information.
 
 when:
   - event: pull_request
@@ -11,8 +12,10 @@ steps:
     image: python:latest
     commands:
       - pip install uv
+      # uv normally installs in a venv, but I could not work out how to activate it. Therefore, I used this work around.
       - uv export --format requirements.txt > requirements.txt
       - uv pip install --system -r requirements.txt
+      # This needs all the dependencies since they include type hints.
       - mypy src
 depends_on:
   - security
diff --git a/Python/.woodpecker/security.yaml b/Python/.woodpecker/security.yaml
index 078fbbb..5817822 100644
--- a/Python/.woodpecker/security.yaml
+++ b/Python/.woodpecker/security.yaml
@@ -1,4 +1,6 @@
 # Runs bandit to make sure you don't have security issues.
+#
+# See test.yaml for more information.
 
 when:
   - event: pull_request
diff --git a/Python/.woodpecker/test.yaml b/Python/.woodpecker/test.yaml
index 38b16f8..9aa32f3 100644
--- a/Python/.woodpecker/test.yaml
+++ b/Python/.woodpecker/test.yaml
@@ -1,7 +1,16 @@
 # Runs all the unit test with coverage and generates a report.
+#
 # Note that
+#
 #   1. This runs only after security, lint, mypy and docs checks have passed.
+#     a. Security runs bandit.
+#     b. Lint runs ruff.
+#     c. Mypy runs mypy, for typ4e hints.
+#     d. Docs runs pydocstyle and mkdocs — with the material theme since it's the one I use.
 #   2. This uses uv to generate a requirements.txt file.
+#   3. I run from Python 3.10 to 3.13.
+#   4. 3.14 is still in development, but you could add it, and make sure the test failure is none-blocking.
+#   5. I have no idea how to get the coverage report so Woodpeck/Codeberg can display it.
 
 when:
   - event: pull_request
@@ -13,8 +22,10 @@ steps:
     image: python:${TAG}
     commands:
       - pip install uv
+      # uv normally installs in the venv, but I could not work out how to activate it. Therefore, I used this work around.
       - uv export --format requirements.txt > requirements.txt
       - uv pip install --system -r requirements.txt
+      # Running coverage with pytest and generates a report.
       - coverage run --concurrency=thread -m pytest --doctest-modules --slow
       - coverage combine
       - coverage report -m
@@ -28,6 +39,7 @@ matrix:
     - 3.13
 
 depends_on:
+  # See files of the same name here.
   - security
   - lint
   - mypy