doc: Update documentation about changelog generation

Xavier Berger · Xavier Berger · commit 0123ba3e5068 · 2024-06-21T18:36:53.000+02:00
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,4 +1,10 @@
-# Changelog
+!!! Changelog update
+    ChangeLog is only available in [documentation](https://xavierberger.github.io/Solar-Router-for-ESPHome/changelog/).  
+    Changelog is update manually after a new release is published.
 
-!!! note
-    ChangeLog is only populated in [documentation](https://xavierberger.github.io/Solar-Router-for-ESPHome/changelog/) when a new release is published.
+    Changelog is generated using `git-cliff`.  
+    Version are based on tags.  
+    Logs are based on merge commit messages.
+
+    The script `tools\update_documentation.sh` is designed to update `changelog.md`, generate and publish `mkdocs` documentation on [github pages](https://xavierberger.github.io/Solar-Router-for-ESPHome/).  
+    This script is entented to be used by repository maintainer only.
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -58,6 +58,11 @@ A documentation have to be added describing the power meter and how to configure
 
 Documentation is written using [mkdocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
 
-To install mkdocs, you need to install [Python](https://python.org) and then install the required module with the following command `pip install -r requirements.txt`.
+To install `mkdocs`, you need to install [Python](https://python.org) and then :
 
-Documentation is stored in `docs` directory. To see you modification in real time in your browser, execute the command `mkdocs serve` and browse [http://127.0.0.1:8000](http://127.0.0.1:8000)
+- Create a virtual environment (see [Python documentation](https://docs.python.org/3/library/venv.html)).
+- Install the required module with the following command `pip install -r requirements.txt`.
+
+Documentation is stored in `docs` directory. To see you modification in real time in your browser, execute the command `mkdocs serve` and browse [http://127.0.0.1:8000](http://127.0.0.1:8000)
+
+{% include "changelog.md"%}
diff --git a/docs/images/SolarRouterBanner.png b/docs/images/SolarRouterBanner.png
diff --git a/docs/images/SolarRouterBanner.xcf b/docs/images/SolarRouterBanner.xcf
diff --git a/docs/index.md b/docs/index.md
@@ -11,4 +11,5 @@ This integration enables users to effortlessly monitor and control the router's
     Please read the [disclaimer](disclamer.md) before proceeding with the **Solar Router for ESPHome** project. 
 
 ![SolarRouterClosed](images/SolarRouterClosed.png){width=350}
-![Dashboard](images/SolarRouterInHomeAssistantDashboard.png){width=350}
+![Dashboard](images/SolarRouterInHomeAssistantDashboard.png){width=350}
+
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -54,3 +54,4 @@ plugins:
   - git-revision-date-localized:
       type: datetime
   - glightbox
+  - include-markdown
diff --git a/requirements.txt b/requirements.txt
@@ -1,7 +1,8 @@
 mkdocs
+mkdocs-git-revision-date-localized-plugin
+mkdocs-glightbox
+mkdocs-include-markdown-plugin
 mkdocs-material
 mkdocs-material-extensions
 mkdocs-minify-plugin
-mkdocs-git-revision-date-localized-plugin
-mkdocs-glightbox
 pymdown-extensions
diff --git a/tools/update_documantation.sh b/tools/update_documantation.sh
@@ -5,7 +5,7 @@ pushd "${SCRIPT_DIR}/.." > /dev/null
 git cliff > docs/changelog.md
 code docs/changelog.md
 
-read -r -p "Ready to publish? [Y/N]: " response
+read -r -p "Ready to publish? [y/N]: " response
 
 if [[ "$response" =~ ^[Yy]$ ]]; then
     mkdocs gh-deploy
