stove/rougail
3
0
Fork 0
Code Issues 5 Pull requests 1 Projects Releases Wiki Activity

jinja ok

Browse source
This commit is contained in:
gwen 2026-02-26 16:36:43 +01:00
parent 7b5c7b80ec
commit 3bfb517087
1 changed files with 18 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
docs/tutorial/jinja.rst
View file

@ -11,8 +11,7 @@ Playing with Jinja
We will learn how to insert `Jinja templating language <https://jinja.palletsprojects.com/en/stable/>`_ into our structure files. We will learn how to insert `Jinja templating language <https://jinja.palletsprojects.com/en/stable/>`_ into our structure files.
Please note that we do not intend to template our YAML files. Please note that we do not intend to template our YAML files.
That is a completely different activity. 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 .. prerequisites:: Prerequisites
@ -32,9 +31,9 @@ Playing with Jinja
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
git switch --detach v1.1_070 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 <https://jinja.palletsprojects.com/en/stable/>`_ in our structure file. We are going to embed some `Hinja templating code <https://jinja.palletsprojects.com/en/stable/>`_ in our structure file.
.. glossary:: .. glossary::
@ -103,7 +102,7 @@ Here is our structure file:
when: HTTPS 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 .. 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 If this variable is set to `true`, the `"HTTPS is same has HTTP"` expression
will appear. will appear.
.. note:: Have a look at the `jinja website's test section <https://jinja.palletsprojects.com/en/stable/templates/#tests>`_ .. note:: Have a look at the `Jinja website's test section <https://jinja.palletsprojects.com/en/stable/templates/#tests>`_
for a closer look about testing a variable. for a closer look about testing a variable.
But first, let's set our `use_for_https` variable to `false`: 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" because has property "hidden"
(HTTPS is same has HTTP) (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. as an explanation inside the error message.
.. type-along:: Without calculation
.. 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.
Let's reason on the previous HTTPS proxy configuration's manual mode settings: 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: hidden:
variable: _.use_for_https 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, depending on the value of another variable. This is what we saw before,
how to hide a variable. 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. 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 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, The fact is that it has same result, but it opens more possibilities,
we will see them later. we will see them later.
@ -253,14 +248,14 @@ Jinja with a description
git switch --detach v1.1_071 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 That allows the calculation performed by the Jinja code to be understood rapidely
without having to read the code itself. without having to read the code itself.
This is useful for the :term:`integrators <integrator>` who review these :term:`structure files <structure file>`. This is useful for the :term:`integrators <integrator>` who review these :term:`structure files <structure file>`.
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_071/firefox/20-manual.yml .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_071/firefox/20-manual.yml
:language: yaml :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 %YAML 1.2
@ -312,26 +307,7 @@ With this rougail command:
rougail -m firefox -o doc --doc.output_format html > readme.html rougail -m firefox -o doc --doc.output_format html > readme.html
It outputs an HTML report, here is a part of it: It outputs an HTML report, here is a part of it about the `https_proxy` with the `hidden` property:
.. code-block:: html
<i>HTTPS</i> Proxy or <i>SOCKS</i> Proxy
This family builds families dynamically.
<b>Path</b>: <ul><li>manual.<i>https</i>_proxy</li>
<li>manual.<i>socks</i>_proxy</li></ul>
<mark><i>hidden</i></mark>
<b>Hidden</b>: in HTTPS case if "manual.use_for_https" is set to "true" <br/>
<b>Identifiers</b>:
<ul><li>HTTPS</li>
<li>SOCKS</li></ul>
As for the `https_proxy` with the `hidden` property, we have this:
.. raw:: html .. raw:: html
:class: output :class: output
@ -464,17 +440,20 @@ the `use_for_https` variable is set to `true` and the identifier is HTTPS
.. keypoints:: Key points .. 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** **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 describe a calcuation
- we know how to output some documentation (in markdown or in html) of the :term:`configuration` - we know how to output some documentation (in markdown or in html) of the :term:`configuration`
- we can calculate with a dynamic family identifer - we can calculate with a dynamic family identifer
**keywords** **keywords**
- jinja type calcuation for a hidden property - Jinja type calcuation for a hidden property
- jinja calcuation's description - Jinja calcuation's description
- identifier type parameter - identifier type parameter
Here we have come to the possibility of making any kind of calculations based on the state of the :term:`configuration`. Here we have come to the possibility of making any kind of calculations based on the state of the :term:`configuration`.