Merge pull request #3801 from camptocamp/ghci/backport/3799-to-master

[Backport master] Add generated SETTINGS.md with environment variables documentation

Author: sbrunner

.github/workflows/main.yaml

@@ -51,6 +51,18 @@ jobs:
         env:
           GITHUB_EVENT: ${{ toJson(github) }}
 
+      - name: Settings documentation
+        run: make settings-doc
+      - run: git diff --exit-code --color
+      - run: git diff --patch > /tmp/settings-doc.patch; git reset --hard || true
+        if: failure()
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: Update settings documentation.patch
+          path: /tmp/settings-doc.patch
+          retention-days: 1
+        if: failure()
+
       - name: Build
         run: make build
 

.pre-commit-config.yaml

@@ -53,6 +53,10 @@ repos:
       - id: prettier
         additional_dependencies:
           - prettier@2.8.4
+        exclude: |-
+          (?x)^(
+            tilecloud_chain/SETTINGS\.md
+          )$
   - repo: https://github.com/camptocamp/jsonschema-gentypes
     rev: 2.13.0
     hooks:

Makefile

@@ -43,6 +43,16 @@ tests: build ## Run the unit tests
 
 PYTEST_ARGS ?= --last-failed --full-trace
 
+.PHONY: settings-doc
+settings-doc: ## Generate settings documentation
+	poetry install --no-root
+	PYTHONPATH=. poetry run settings-doc generate \
+		--class=tilecloud_chain.settings.Settings \
+		--output-format=markdown \
+		--update=tilecloud_chain/SETTINGS.md \
+		--between "<!-- generated env. vars. start -->" "<!-- generated env. vars. end -->" \
+		--heading-offset=1
+
 .PHONY: tests-fast
 tests-fast:
 	docker compose up -d

README.md

@@ -167,7 +167,7 @@ make tests
 
 - [Usage Guide](https://github.com/camptocamp/tilecloud-chain/blob/master/tilecloud_chain/USAGE.rst)
 - [Configuration Reference](https://github.com/camptocamp/tilecloud-chain/blob/master/tilecloud_chain/CONFIG.md)
-- [Environment variables](https://github.com/camptocamp/tilecloud-chain/blob/master/tilecloud_chain/settings.py)
+- [Environment variables](https://github.com/camptocamp/tilecloud-chain/blob/master/tilecloud_chain/SETTINGS.md)
 
 ## Contributing
 

ci/requirements.txt

@@ -1,3 +1,4 @@
+poetry==2.4.1
 c2cciutils==1.7.5
 poetry-plugin-export==1.10.0
 pre-commit==4.6.2

poetry.lock

@@ -63,6 +63,7 @@ pytest-check = "2.9.1"
 types-pyyaml = "6.0.12.20260724"
 ruff = "0.16.2"
 pylint = "4.0.7"
+settings-doc = "4.3.2"
 
 [tool.poetry-dynamic-versioning]
 enable = true