From 0f8f4a959a1a10d8b51bfb59cf8de60cb80800d5 Mon Sep 17 00:00:00 2001
From: Julien Moura <julien.moura@oslandia.com>
Date: Tue, 20 Jan 2026 21:27:37 +0100
Subject: [PATCH 1/2] add(docs): auto generate QDT snippet and use
 keepachangelog to retrieve latest published verison from CHANGELOG.md

---
 .gitignore                     |  1 +
 docs/conf.py                   | 54 ++++++++++++++++++++++++++--------
 docs/index.md                  |  1 +
 docs/usage/with_qdt.md         | 10 +++++++
 requirements/documentation.txt |  1 +
 5 files changed, 55 insertions(+), 12 deletions(-)
 create mode 100644 docs/usage/with_qdt.md

diff --git a/.gitignore b/.gitignore
index 9f9bcd9..0b91cb6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -146,3 +146,4 @@ profile_manager/**/*.db
 # packaging
 plugins.xml
 zip_build
+docs/static/qdt_snippet.json
diff --git a/docs/conf.py b/docs/conf.py
index 2f7838c..9254b7d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -5,28 +5,38 @@
 """
 
 # standard
-import sys
+import json
+import logging
 from datetime import datetime
-from os import path
+from pathlib import Path
+from typing import Union
 
-sys.path.insert(0, path.abspath(".."))  # move into project package
+# 3rd party
+import keepachangelog
 
 # Package
 from profile_manager import __about__
 
+logger: logging.Logger = logging.getLogger(__name__)
+
 # -- Project information -----------------------------------------------------
-author = __about__.__author__
-copyright = __about__.__copyright__
-description = __about__.__summary__
-project = __about__.__title__
-version = release = __about__.__version__
+changes: dict[str, dict] = keepachangelog.to_dict("../CHANGELOG.md")
+latest_version: str = [
+    v for v in changes.keys() if v not in ("Unreleased", "version_tag")
+][0]
+
+author: str = __about__.__author__
+copyright: str = __about__.__copyright__
+description: str = __about__.__summary__
+project: str = __about__.__title__
+version = release = latest_version
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
+extensions: list[str] = [
     # Sphinx included
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
@@ -127,14 +137,33 @@
 myst_url_schemes = ("http", "https", "mailto")
 
 
+# -- Functions ------------------------------------------------------------------
+def generate_qdt_snippet(_) -> None:
+    """Generate QDT snippet for profiles.json files."""
+    logger.warning("=== START GENERATING QDT SNIPPET ===")
+
+    qdt_snippet: dict[str, Union[str, bool, int]] = {
+        "name": "Profile Manager",
+        "folder_name": "profile_manager",
+        "official_repository": True,
+        "plugin_id": 3547,
+        "version": f"{ latest_version }",
+    }
+
+    with Path("./docs/static/qdt_snippet.json").open("w", encoding="UTF8") as wf:
+        wf.write(json.dumps(qdt_snippet, indent=4, sort_keys=True))
+
+
 # -- API Doc --------------------------------------------------------
 # run api doc
 def run_apidoc(_):
     from sphinx.ext.apidoc import main
 
-    cur_dir = path.normpath(path.dirname(__file__))
-    output_path = path.join(cur_dir, "_apidoc")
-    modules = path.normpath(path.join(cur_dir, "../profile_manager"))
+    logger.info("=== START SPHINX API AUTODOC ===")
+
+    cur_dir = Path(__file__).parent.resolve()
+    output_path = str(cur_dir.joinpath("_apidoc").resolve())
+    modules = str(cur_dir.joinpath("../profile_manager/").resolve())
     exclusions = ["../.venv", "../tests"]
     main(["-e", "-f", "-M", "-o", output_path, modules] + exclusions)
 
@@ -142,3 +171,4 @@ def run_apidoc(_):
 # launch setup
 def setup(app):
     app.connect("builder-inited", run_apidoc)
+    app.connect("builder-inited", generate_qdt_snippet)
diff --git a/docs/index.md b/docs/index.md
index 99e0a43..ff96ce5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -16,6 +16,7 @@ caption: Usage
 maxdepth: 1
 ---
 usage/installation
+usage/with_qdt
 ```
 
 ```{toctree}
diff --git a/docs/usage/with_qdt.md b/docs/usage/with_qdt.md
new file mode 100644
index 0000000..dff82b9
--- /dev/null
+++ b/docs/usage/with_qdt.md
@@ -0,0 +1,10 @@
+# Using this plugin with QGIS Deployment Toolbelt (QDT)
+
+If you want to use this plugin with [QGIS Deployment Toolbelt (QDT)](https://qgis-deployment.github.io/qgis-deployment-toolbelt-cli/), you can add the following snippet to your `profile.json` file, under the `plugins` attribute:
+
+```{eval-rst}
+.. literalinclude:: ../static/qdt_snippet.json
+  :language: json
+```
+
+Remember to replace the `version` attribute with the version you want to install.
diff --git a/requirements/documentation.txt b/requirements/documentation.txt
index a9308ca..97486f4 100644
--- a/requirements/documentation.txt
+++ b/requirements/documentation.txt
@@ -2,6 +2,7 @@
 # -----------------------
 
 furo>=2024
+keepachangelog>=2.0.0
 myst-parser[linkify]>=2
 sphinx-autobuild>=2024
 sphinx-copybutton>=0.5,<1

From 691a7edf8e1dbf6b3b9c440573e139a576f8c98a Mon Sep 17 00:00:00 2001
From: Julien Moura <julien.moura@oslandia.com>
Date: Tue, 20 Jan 2026 21:30:57 +0100
Subject: [PATCH 2/2] fix(docs): restore sys path customization

---
 docs/conf.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index 9254b7d..3430440 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -7,10 +7,14 @@
 # standard
 import json
 import logging
+import sys
 from datetime import datetime
 from pathlib import Path
 from typing import Union
 
+# move into project package
+sys.path.insert(0, f"{Path(__file__).parent.parent.resolve()}")
+
 # 3rd party
 import keepachangelog