diff --git a/docs/tutorial/jinja.rst b/docs/tutorial/jinja.rst index 124e8aad8..c79f5f463 100644 --- a/docs/tutorial/jinja.rst +++ b/docs/tutorial/jinja.rst @@ -236,13 +236,194 @@ Now we can code the same behavior in a somehow different way: HTTPS is same has HTTP {% endif %} -This code has the same result but 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 a jinja parameter. The hidden process is done by a calculation. -The fact is that it has same result, but it wil open more possibilities. +The fact is that it has same result, but it opens more possibilities, +we will see them later. -FIXME +Jinja with a description +----------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_071` version:: + + git switch --detach v1.1_071 + +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 + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + + use_for_https: true # Also use this proxy for HTTPS + + '{{ identifier }}_proxy': + description: '{{ identifier }} Proxy' + hidden: + jinja: |- + {% if _.use_for_https %} + HTTPS is same has HTTP + {% endif %} + description: in HTTPS case if "_.use_for_https" is set to "true" + dynamic: + - HTTPS + - SOCKS + + address: + description: '{{ identifier }} address' + default: + variable: __.http_proxy.address + + port: + description: '{{ identifier }} port' + default: + variable: __.http_proxy.port + + version: + description: SOCKS host version used by proxy + choices: + - v4 + - v5 + default: v5 + disabled: + type: identifier + when: HTTPS + ... + +This description will appear `in the documentation output for the family `_ + +With this rougail command: + +.. code-block:: bash + + rougail -m firefox -o doc --doc.output_format html > readme.html + +We have an HTML report that contains: + +.. 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
+ +We can see that we have for the `manual.https_proxy` family: + +.. raw:: html + + manual.https_proxy
+ + Hidden: in HTTPS case if "manual.use_for_https" is set to "true"
+ + Identifiers: +
  • HTTPS
  • + +Jinja with a parameter +--------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_072` version:: + + git switch --detach v1.1_072 + +Regarding dynamic families as in the use case we are dealing with, here is an interesting Rougail feature: +it is possible to retrieve the family identifiers and declare them as parameters in the Jinja calculation. + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_072/firefox/20-manual.yml + :language: yaml + :caption: The :file:`firefox/20-manual.yml` structure file with an identifier type parameter in the hidden property + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + + use_for_https: true # Also use this proxy for HTTPS + + '{{ identifier }}_proxy': + description: '{{ identifier }} Proxy' + hidden: + jinja: |- + {% if my_identifier == 'HTTPS' and _.use_for_https %} + HTTPS is same has HTTP + {% endif %} + description: in HTTPS case if "_.use_for_https" is set to "true" + params: + my_identifier: + type: identifier + dynamic: + - HTTPS + - SOCKS + + address: + description: '{{ identifier }} address' + default: + variable: __.http_proxy.address + + port: + description: '{{ identifier }} port' + default: + variable: __.http_proxy.port + + version: + description: SOCKS host version used by proxy + choices: + - v4 + - v5 + default: v5 + disabled: + type: identifier + when: HTTPS + ... + +We have added an `identifier` type parameter to the `hidden` property: + +.. code-block:: yaml + + hidden: + params: + my_identifier: + type: identifier + +Thus we can refine our Jinja code and hide the `https_proxy` dynamic family, +that is only in the case where the identifier is `HTTPS`. + +.. code-block:: yaml + + hidden: + jinja: |- + {% if my_identifier == 'HTTPS' and _.use_for_https %} + HTTPS is same has HTTP + {% endif %} + +In this Jinja code, we can understand that only the `https_proxy` dynamic family +will be hidden when the `_.use_for_https` variable is set to `true`. .. keypoints:: Key points