rougail/docs/tutorial/examples.rst

A full documented variable 
==============================

.. objectives:: Objectives
   
   You’ve no doubt wondered, on more than one occasion, how to do this or that; 
   even if you have the documentation, it’s not clear enough. 
   
   What would make it clear is a good example.
   
   With Rougail, you can add examples into the structural specifications of a variable or a family, illustrative examples.
   That is what we will look at in this section. Documentation through examples.

.. prerequisites:: Prerequisites

    - We assume that Rougail's library is :ref:`installed <installation>` on your computer.

    - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
      by checking out the corresponding tag of the `rougail-tutorials` git repository.
      Each tag corresponds to a stage of progress in the tutorial.
      Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.

    If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
    this workshop page corresponds to the tags :tutorial:`v1.1_120 <src/tag/v1.1_120/README.md>` to :tutorial:`v1.1_121 <src/tag/v1.1_121/README.md>`
    in the repository.

    ::

       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
       git switch --detach v1.1_120


Examples
-----------

How to define example usage? All you need to do is add an `examples` parameter to the structural definition of your variable.
Let's give some usage examples of how to use our `no_proxy` variable:


.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/firefox/40-no_proxy.yml
   :language: yaml
   :caption: The :file:`firefox/40-no_proxy` structure definition file with an `example` parameter

.. 
    %YAML 1.2
    ---
    version: 1.1

    no_proxy:
      description: Address for which proxy will be desactivated
      examples:
        - .mozilla.org
        - .net.nz
        - 192.168.1.0/24
      type: domainname
      params:
        allow_ip: true
        allow_cidr_network: true
        allow_without_dot: true
        allow_startswith_dot: true
      multi: true
      mandatory: false
      disabled:
        variable: _.proxy_mode
        when: No proxy
    ...

.. attention:: Note: the `examples` parameter does not specify default values. **It's just examples, it's not a setting**.

Here we can see that there are no default values set and as our variable is not :term:`mandatory`, 
if we don't set values in the user data files as the `no_proxy` variable is :term:`multi`, the `no_proxy` value will be the empty list `[]`:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/config.yml
   :language: yaml
   :caption: The :file:`config/03/config.yml` user data file with an `example` parameter but no value set

..
    ---
    proxy_mode: Automatic proxy configuration URL
    auto: https://auto.proxy.net/wpad.dat
    no_proxy:
      - example.net
      - 192.168.1.0/24


.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/cmd_ro.txt
   :class: terminal

..
    rougail -m firefox/ --types types/proxy -u yaml -yf config/01/config.yml

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/output_ro.html
   :class: output

..
    ╭────────────── Caption ───────────────╮
    │ Variable Default value               │
    │          Modified value              │
    │          (⏳ Original default value) │
    ╰──────────────────────────────────────╯
    Variables:
    ┣━━ 📓 Configure Proxy Access to the Internet: Automatic proxy configuration URL ◀ loaded from the YAML file "config/03/config.yml"
    ┃   (⏳ No proxy)
    ┣━━ 📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ loaded from the YAML file "config/03/config.yml"
    ┗━━ 📓 Address for which proxy will be desactivated: []

.. type-along:: If we set some user data values 

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/config.yml
   :language: yaml
   :caption: The :file:`config/03/config.yml` user data file with some value set

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/cmd_ro.txt
   :class: terminal

..
    rougail -m firefox/ --types types/proxy -u yaml -yf config/02/config.yml

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/output_ro.html
   :class: output

..
    ╭────────────── Caption ───────────────╮
    │ Variable Modified value              │
    │          (⏳ Original default value) │
    ╰──────────────────────────────────────╯
    Variables:
    ┣━━ 📓 Configure Proxy Access to the Internet: Automatic proxy configuration URL
    ┃   ◀ loaded from the YAML file "config/02/config.yml" (⏳ No proxy)
    ┣━━ 📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ 
    ┃   loaded from the YAML file "config/02/config.yml"
    ┗━━ 📓 Address for which proxy will be desactivated:
        ┣━━ example.net ◀ loaded from the YAML file "config/02/config.yml"
        ┗━━ 192.168.1.0/24 ◀ loaded from the YAML file "config/02/config.yml"

.. note:: In all cases, we can see that none of the values ​​cited in the examples (`.mozilla.org`, `.net.nz`) appear.