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.
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 <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::
@ -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 <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.
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 <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
: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
<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:
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`.