.. _documented_variable:

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**.

If we launch the Rougail CLI on user data:

.. 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

we can see that the `no_proxy` variable has no user data settings.

.. 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

We do indeed obtain the value empty list `[]` for the `no_proxy` variable:

.. 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 

Just to be thorough, let's look at what happens in a case where there is a value for `no_proxy` entered in the user data file:

.. 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

We launch the Rougail CLI:

.. 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

And we have the `no_proxy`'s expected value. No trace in the output of the examples settings of the variable:

.. 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"

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


.. type-along:: In that case, is there a use for these examples? 

This examples parameter is useful when generating variable documentation. That's where the examples appear.

If we launch the Rougail CLI for the documentation generation:

.. code-block:: bash

   rougail -m firefox --types types/proxy -o doc --doc.output_format html

We have this output:

.. raw:: html
   :class: output

    <table>
    <thead>
    <tr><th>Variable                                                                                                                                                                                               </th><th>Description  </th></tr>
    </thead>
    <tbody>
    <tr><td><b>auto</b><br/><mark><a href='https://rougail.readthedocs.io/en/latest/variable.html#variables-types'>web address</a></mark> <mark>mandatory</mark> <mark><i>disabled</i></mark>                      </td><td>Automatic proxy configuration URL.<br/><b>Validators</b>: <ul><li>well-known ports (1 to 1023) are allowed</li>
    <li>registred ports (1024 to 49151) are allowed</li>
    <li>type domainname</li>
    <li>the domain name can be a hostname</li></ul><br/><b>Disabled</b>: when the variable "proxy_mode" hasn't the value "Automatic proxy configuration URL"              </td></tr>
    <tr><td><b>no_proxy</b><br/><mark><a href='https://rougail.readthedocs.io/en/latest/variable.html#variables-types'>domainname</a></mark> <mark>multiple</mark> <mark><i>disabled</i></mark> <mark>unique</mark></td><td>Address for which proxy will be desactivated.<br/><b>Validators</b>: <ul><li>type domainname</li>
    <li>the domain name can starts by a dot</li>
    <li>the domain name can be a hostname</li>
    <li>the domain name can be an IP</li>
    <li>the domain name can be network in CIDR format</li></ul><br/><b>Examples</b>: <ul><li>.mozilla.org</li>
    <li>.net.nz</li>
    <li>192.168.1.0/24</li></ul><br/><b>Disabled</b>: when the variable "proxy_mode" has the value "No proxy"              </td></tr>
    </tbody>
    </table>

..
        ├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────┤
        │ no_proxy                                                                                    │ Address for which proxy will be desactivated.                                                │
        │  domainname   multiple   disabled   unique                                                  │ Validators:                                                                                  │
        │                                                                                             │ • type domainname                                                                            │
        │                                                                                             │ • the domain name can starts by a dot                                                        │
        │                                                                                             │ • the domain name can be a hostname                                                          │
        │                                                                                             │ • the domain name can be an IP                                                               │
        │                                                                                             │ • the domain name can be network in CIDR format                                              │
        │                                                                                             │ Examples:                                                                                    │
        │                                                                                             │ • .mozilla.org                                                                               │
        │                                                                                             │ • .net.nz                                                                                    │
        │                                                                                             │ • 192.168.1.0/24                                                                             │
        │                                                                                             │ Disabled: when the variable "proxy_mode" has the value "No proxy"                            │
        └─────────────────────────────────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────┘
        
we can see that this time the examples (`.mozilla.org`, `.net.nz`) appear.

Help
-------

.. type-along:: For those who follow the tutorial with the help of the git repository

    Now you need to checkout the :tutorial:`v1.1_121 <src/tag/v1.1_121/README.md>` version::

          git switch --detach v1.1_121

Could we define personalized assistance, in the same way that we defined examples?

Yes, very simply: we add a `help` parameter to our `no_proxy` variable: 

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


In the same way, this help `"Connections to localhost, 127.0.0.1/8 and ::1 are never proxied"` will appear in the documentation:

.. raw:: html
   :class: output

    <table>
    <thead>
    <tr><th>Variable                                                                                                                                                                                               </th><th>Description  </th></tr>
    </thead>
    <tbody>
    <tr><td><b>auto</b><br/><mark><a href='https://rougail.readthedocs.io/en/latest/variable.html#variables-types'>web address</a></mark> <mark>mandatory</mark> <mark><i>disabled</i></mark>                      </td><td>Automatic proxy configuration URL.<br/><b>Validators</b>: <ul><li>well-known ports (1 to 1023) are allowed</li>
    <li>registred ports (1024 to 49151) are allowed</li>
    <li>type domainname</li>
    <li>the domain name can be a hostname</li></ul><br/><b>Disabled</b>: when the variable "proxy_mode" hasn't the value "Automatic proxy configuration URL"              </td></tr>
    <tr><td><b>no_proxy</b><br/><mark><a href='https://rougail.readthedocs.io/en/latest/variable.html#variables-types'>domainname</a></mark> <mark>multiple</mark> <mark><i>disabled</i></mark> <mark>unique</mark></td><td>Address for which proxy will be desactivated.<br/>Connections to localhost, 127.0.0.1/8 and ::1 are never proxied.<br/><b>Validators</b>: <ul><li>type domainname</li>
    <li>the domain name can starts by a dot</li>
    <li>the domain name can be a hostname</li>
    <li>the domain name can be an IP</li>
    <li>the domain name can be network in CIDR format</li></ul><br/><b>Examples</b>: <ul><li>.mozilla.org</li>
    <li>.net.nz</li>
    <li>192.168.1.0/24</li></ul><br/><b>Disabled</b>: when the variable "proxy_mode" has the value "No proxy"              </td></tr>
    </tbody>
    </table>
 
.. type-along:: The difference between the `description` parameter and the `help` parameter

The help section serves as supplementary documentation regarding the description parameter.
Please do not mix the :term:`description` parameter and the :term:`help` parameter's variable usage.

A :term:`description` allows you to describe the expected value(s) of a variable concisely and clearly.
It is designed to be clear precise and short, much like the help of some 
command-line utility when you type the command with the `--help` or `-h` option.

A :term:`help` helps to clarify any ambiguity about the variable’s purpose. It can be long and detailed.

We can set :term:`help` attribute to a variable or to a family.

.. keypoints:: Key points

   - We have seen how to give examples, simply with the `examples` parameter
   - We have seen how to specify a help, simply with the `help` parameter

