diff --git a/docs/tutorial/dynfam.rst b/docs/tutorial/dynfam.rst new file mode 100644 index 000000000..a093fa999 --- /dev/null +++ b/docs/tutorial/dynfam.rst @@ -0,0 +1,101 @@ + +A dynamic family +================ + +.. objectives:: Objectives + + In this section we will learn how to create a dynamically created family. + +.. prerequisites:: Reminder + + We handled the HTTPS mode in the previous section. But there's more. + Let's have a look at the firefox's configuration page: + +.. image:: images/soksv5.png + +In fact we shall not only handle the HTTPS configuration but the SOCKS configuration too. +And we can see that these two group of variables are very similar: +they both have two variables, that is a host and a port. + +Creating a generic family +---------------------------- + +There are two proxies that are to be configured : + +- the HTTP proxy +- the SOCKS proxy + +It's not the place here to describe what the HTTP and SOCKS protocols are. +The interesting point is that : + +- they are similar in terms of our firefox's configuration +- we can use a generic family declaration mode in this use case (we call this genericity "dynamic creation") + +Instead of doing something like this: + +.. code-block:: yaml + + https_proxy: + description: HTTPS Proxy + ... + + address: + description: HTTPS address + ... + + port: + description: HTTPS Port + ... + +And this: + + +.. code-block:: yaml + + sock_proxy: + description: SOCKS Proxy + ... + + address: + description: SOCKS address + ... + + port: + description: SOCKS Port + ... + +With Rougail we have the ability to say this: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_037/firefox/20-manual.yml + :language: yaml + :caption: firefox/20-proxy.yml + +What is an identifier? +------------------------- + +We define what we call an :term:`identifier`, which is a local variable, used only for creating +multiple families at one time (that is, being more generic in our declaration style). +This is this syntax that allows the declaration of multiple families at one time: + +.. code-block:: yaml + + "{{ identifier }}_proxy": + description: "{{ identifier }} Proxy" + dynamic: + - HTTPS + - SOCKS + +This identifier is a parameter that enables us to create two families named `https_proxy` and `socks_proxy`. + +.. note:: The declaration syntax is a :term:`jinja` templating syntax, which is commonly used + in the python coding field. + +So yes, we have gained in genericity but we have lost in readability, you would say. +But we haven't just been generic. We now have the ability to create conditional hidden family +(and not only conditionnal hidden variables like we did earlier). + +A conditional hidden family with jinja +------------------------------------------ + + + diff --git a/docs/tutorial/images/soksv5.png b/docs/tutorial/images/soksv5.png new file mode 100644 index 000000000..b7ca7aa08 Binary files /dev/null and b/docs/tutorial/images/soksv5.png differ