From 3bfb517087a87cfe9f7de002b60c4701e104d8c2 Mon Sep 17 00:00:00 2001 From: gwen Date: Thu, 26 Feb 2026 16:36:43 +0100 Subject: [PATCH] jinja ok --- docs/tutorial/jinja.rst | 57 +++++++++++++---------------------------- 1 file changed, 18 insertions(+), 39 deletions(-) diff --git a/docs/tutorial/jinja.rst b/docs/tutorial/jinja.rst index 653b22d49..42b7598ce 100644 --- a/docs/tutorial/jinja.rst +++ b/docs/tutorial/jinja.rst @@ -11,8 +11,7 @@ Playing with Jinja We will learn how to insert `Jinja templating language `_ into our structure files. Please note that we do not intend to template our YAML files. That is a completely different activity. - We will simply insert YAML code to calculate variable, property, or parameter values. - + We will simply insert YAML code to calculate the value of a variable, a property, or a parameter. .. prerequisites:: Prerequisites @@ -32,9 +31,9 @@ Playing with Jinja git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch --detach v1.1_070 -.. type-along:: Why the jinja templating engine ? +.. type-along:: Why the Jinja templating engine ? -We are going to embed some `jinja templating code `_ in our structure file. +We are going to embed some `Hinja templating code `_ in our structure file. .. glossary:: @@ -103,7 +102,7 @@ Here is our structure file: when: HTTPS ... -In this jinja code, we are testing the `use_for_https` variable: +In this Jinja code, we are testing the `use_for_https` variable: .. code-block:: jinja @@ -114,7 +113,7 @@ In this jinja code, we are testing the `use_for_https` variable: If this variable is set to `true`, the `"HTTPS is same has HTTP"` expression will appear. -.. note:: Have a look at the `jinja website's test section `_ +.. note:: Have a look at the `Jinja website's test section `_ for a closer look about testing a variable. But first, let's set our `use_for_https` variable to `false`: @@ -199,14 +198,10 @@ Then we have an error: because has property "hidden" (HTTPS is same has HTTP) -.. note:: Note that we can see the "HTTPS is same has HTTP" string (the one that was present in the jinja code) +.. note:: Note that we can see the "HTTPS is same has HTTP" string (the one that was present in the Jinja code) as an explanation inside the error message. - -.. type-along:: What can be calculated? - -We have seen that the `disabled` or `hidden` properties could be calculated. -The default values can be calculated too. We'll see a bunch of examples later on. +.. type-along:: Without calculation Let's reason on the previous HTTPS proxy configuration's manual mode settings: @@ -221,7 +216,7 @@ Let's reason on the previous HTTPS proxy configuration's manual mode settings: hidden: variable: _.use_for_https -We see here that the `https_proxy` family is be hidden +We see here that the `https_proxy` family is hidden depending on the value of another variable. This is what we saw before, how to hide a variable. @@ -239,7 +234,7 @@ Now we can code the same behavior in a somehow different way: This code has the same result and yes, it's done in a more complicated way. We have replaced this simple `hidden` property variable parameter by -a jinja parameter. The hidden process is done by a calculation. +a Jinja parameter. The hidden process is done by a calculation. The fact is that it has same result, but it opens more possibilities, we will see them later. @@ -253,14 +248,14 @@ Jinja with a description git switch --detach v1.1_071 -It is preferable to include a description related to the jinja calcuation. +It is preferable to include a description related to the Jinja calcuation. That allows the calculation performed by the Jinja code to be understood rapidely without having to read the code itself. This is useful for the :term:`integrators ` who review these :term:`structure files `. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_071/firefox/20-manual.yml :language: yaml - :caption: The :file:`firefox/20-manual.yml` structure file with a description added to the `jinja` code + :caption: The :file:`firefox/20-manual.yml` structure file with a description added to the `Jinja` code .. %YAML 1.2 @@ -312,26 +307,7 @@ With this rougail command: rougail -m firefox -o doc --doc.output_format html > readme.html -It outputs an HTML report, here is a part of it: - -.. code-block:: html - - HTTPS Proxy or SOCKS Proxy - - This family builds families dynamically. - - Path:
  • manual.https_proxy
    • -
  • manual.socks_proxy
- - hidden - - Hidden: in HTTPS case if "manual.use_for_https" is set to "true"
- - Identifiers: -
  • HTTPS
    • -
  • SOCKS
- -As for the `https_proxy` with the `hidden` property, we have this: +It outputs an HTML report, here is a part of it about the `https_proxy` with the `hidden` property: .. raw:: html :class: output @@ -464,17 +440,20 @@ the `use_for_https` variable is set to `true` and the identifier is HTTPS .. keypoints:: Key points + We have seen that the `disabled` or `hidden` properties could be calculated. + The default values can be calculated too. We'll see a bunch of examples later on. + **progress** - - calculation with a jinja type calculation: we can hide a family + - calculation with a Jinja type calculation: we can hide a family - we know how to describe a calcuation - we know how to output some documentation (in markdown or in html) of the :term:`configuration` - we can calculate with a dynamic family identifer **keywords** - - jinja type calcuation for a hidden property - - jinja calcuation's description + - Jinja type calcuation for a hidden property + - Jinja calcuation's description - identifier type parameter Here we have come to the possibility of making any kind of calculations based on the state of the :term:`configuration`.