Docs: add rules context dynamically (#485)

In this PR we generate the rules context dynamically for the
documentation using a Sphinx hook. Then it's embedded like this:


![image](https://github.com/Guts/qgis-deployment-cli/assets/1596222/288776be-7a9a-448c-8e86-3871d9189c9f)


To merge after #484.

.gitignore

@@ -142,3 +142,4 @@ build_environment_report*.txt
 safety_report.txt
 bandit_report.csv
 tests/fixtures/http-test-local/qdt-files.json
+docs/reference/rules_context.json

docs/conf.py

@@ -5,6 +5,7 @@
 """
 
 # standard
+import json
 import os
 from datetime import datetime
 from pathlib import Path
@@ -16,6 +17,10 @@
     get_latest_release,
     replace_domain,
 )
+from qgis_deployment_toolbelt.utils.computer_environment import (
+    date_dict,
+    environment_dict,
+)
 
 # -- Build environment -----------------------------------------------------
 on_rtd = os.environ.get("READTHEDOCS", None) == "True"
@@ -212,6 +217,16 @@
 # -- Functions ------------------------------------------------------------------
 
 
+def generate_rules_context(_):
+    """Generate context object as JSON that it passed to rules engine to check profiles
+    conditions."""
+    context_object = {"date": date_dict(), "environment": environment_dict()}
+    with Path("./docs/reference/rules_context.json").open(
+        mode="w", encoding="utf-8"
+    ) as out_json:
+        json.dump(context_object, out_json, sort_keys=True, indent=4)
+
+
 def populate_download_page(_):
     """Generate download section included into installation page."""
     latest_release = get_latest_release(
@@ -264,5 +279,6 @@ def run_apidoc(_):
 
 # launch setup
 def setup(app):
+    app.connect("builder-inited", generate_rules_context)
     app.connect("builder-inited", run_apidoc)
     app.connect("builder-inited", populate_download_page)

docs/development/documentation.md

@@ -20,7 +20,7 @@ Open `docs/_build/index.html` in a web browser.
 ## Write documentation using live render
 
 ```sh
-sphinx-autobuild -b html docs/ docs/_autobuild/ --delay 3 --open-browser --ignore docs/misc/dependencies.md --ignore docs/usage/download_section.md
+sphinx-autobuild -b html docs/ docs/_autobuild/ --delay 3 --open-browser --ignore docs/misc/dependencies.md --ignore docs/reference/rules_context.json --ignore docs/usage/download_section.md
 ```
 
 Your default web browser should be automatically opened on <http://localhost:8000> displaying the HTML render which will be  updated when a file is saved.

docs/reference/qdt_profile.md

@@ -33,6 +33,19 @@ You can add rules to make the profile deployment conditional. In the following e
 }
 ```
 
+The rules engine is based on [Python Rule Engine](https://github.com/santalvarez/python-rule-engine/) project whom rules syntax belongs to [JSON Rules Engine](https://github.com/CacheControl/json-rules-engine).
+
+### Conditions
+
+Rules is a set of conditions that use logical operators to compare values with context (a set of facts) which is exposed as a JSON object. Here comes the context for a Linux environment:
+
+```{eval-rst}
+.. literalinclude:: ./rules_context.json
+  :language: json
+```
+
+----
+
 ## Model definition
 
 The project comes with a [JSON schema](https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/profile/qgis_profile.json) describing the model of a profile: