From 8e17e3954e756d57e569b28ada9d844ff1d3166d Mon Sep 17 00:00:00 2001
From: Julien Moura <julien.moura@oslandia.com>
Date: Tue, 17 Dec 2024 16:00:42 +0100
Subject: [PATCH 1/3] fix(docs): page was not part of doc build

---
 docs/development/{development.md => setup.md} | 0
 docs/index.md                                 | 2 +-
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename docs/development/{development.md => setup.md} (100%)

diff --git a/docs/development/development.md b/docs/development/setup.md
similarity index 100%
rename from docs/development/development.md
rename to docs/development/setup.md
diff --git a/docs/index.md b/docs/index.md
index 8038f15..e4e53eb 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -33,7 +33,7 @@ maxdepth: 1
 caption: Contributing
 ---
 development/contribute
-development/environment
+development/setup
 development/documentation
 development/translation
 development/packaging

From dfa01f34f3c3d2408da023d21c5e1fafe261fd0d Mon Sep 17 00:00:00 2001
From: Julien Moura <julien.moura@oslandia.com>
Date: Tue, 17 Dec 2024 16:01:18 +0100
Subject: [PATCH 2/3] add(docs): diagram describing LMFP flow

---
 docs/conf.py                   | 13 ++++++++++++-
 docs/how_does_it_works.md      | 24 ++++++++++++++++++++++++
 docs/index.md                  |  1 +
 requirements/documentation.txt |  1 +
 4 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 docs/how_does_it_works.md

diff --git a/docs/conf.py b/docs/conf.py
index 3f7f267..921bbff 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -32,6 +32,7 @@
     # 3rd party
     "myst_parser",
     "sphinx_copybutton",
+    "sphinxcontrib.mermaid",
 ]
 
 
@@ -48,7 +49,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+# language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -82,6 +83,16 @@
     "qgis": ("https://qgis.org/pyqgis/master/", None),
 }
 
+# mermaid
+mermaid_d3_zoom = True
+mermaid_params = [
+    "--theme",
+    "forest",
+    "--backgroundColor",
+    "transparent",
+]
+mermaid_version = "11.4.1"
+
 # MyST Parser
 myst_enable_extensions = [
     "amsmath",
diff --git a/docs/how_does_it_works.md b/docs/how_does_it_works.md
new file mode 100644
index 0000000..47b1a12
--- /dev/null
+++ b/docs/how_does_it_works.md
@@ -0,0 +1,24 @@
+# How does it work?
+
+```{mermaid}
+---
+title: "How Layers Menu From Project behaves during QGIS launch"
+---
+flowchart TD
+    A@{ shape: circle, label: "QGIS starts" } -->|splash screen displayed| B(load GUI and plugins)
+
+    subgraph "QGIS UI main thread"
+    B -->|GUI is initialized| C@{ shape: curv-trap, label: "QGIS main UI displayed" }
+    C ==> Q((("QGIS is mainly usable")))
+    end
+
+    subgraph "LMFP thread (QgsTask)"
+    C -.->|threaded LMFP| D[[read projects configuration]]
+    D -.-> E[[check project's cache]]
+    E -.->|cache still valid| F(create menus from caches JSON files)
+    F == menus appear in the main UI ==> Q
+    E -.->|cache has expired or is invalid| G(download/copy remote files)
+    G -.->|store cache|H("{path_to_qgis_profile}/cache/menu_from_project")
+    H --> F
+    end
+```
diff --git a/docs/index.md b/docs/index.md
index e4e53eb..ca65ba8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -25,6 +25,7 @@ caption: Usage
 ---
 usage/en_use
 usage/fr_use
+how_does_it_works
 ```
 
 ```{toctree}
diff --git a/requirements/documentation.txt b/requirements/documentation.txt
index ed5910b..156463d 100644
--- a/requirements/documentation.txt
+++ b/requirements/documentation.txt
@@ -5,3 +5,4 @@ furo>=2024
 myst-parser[linkify]>=2
 sphinx-autobuild>=2024
 sphinx-copybutton>=0.5
+sphinxcontrib-mermaid>=1,<2

From 7a83da0e59c90f51a51dd33410b8dfcd42f56de9 Mon Sep 17 00:00:00 2001
From: Julien Moura <julien.moura@oslandia.com>
Date: Tue, 17 Dec 2024 16:03:24 +0100
Subject: [PATCH 3/3] update(docs): add todo for future mermaid update

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

diff --git a/docs/conf.py b/docs/conf.py
index 921bbff..cc0d513 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -91,6 +91,7 @@
     "--backgroundColor",
     "transparent",
 ]
+# TODO: remove next line when the mermaid version shipped with sphinxcontrib-mermaid is 11.4+
 mermaid_version = "11.4.1"
 
 # MyST Parser