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 ` 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 `, this workshop page corresponds to the tags :tutorial:`v1.1_120 ` to :tutorial:`v1.1_121 ` 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 `[]`: 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
Variable Description
auto
web address mandatory disabled 		Automatic proxy configuration URL.
Validators:
  • well-known ports (1 to 1023) are allowed
  • registred ports (1024 to 49151) are allowed
  • type domainname
  • the domain name can be a hostname

Disabled: when the variable "proxy_mode" hasn't the value "Automatic proxy configuration URL"
no_proxy
domainname multiple disabled unique		Address for which proxy will be desactivated.
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"
.. ├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────┤ │ 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 ` 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
Variable Description
auto
web address mandatory disabled 		Automatic proxy configuration URL.
Validators:
  • well-known ports (1 to 1023) are allowed
  • registred ports (1024 to 49151) are allowed
  • type domainname
  • the domain name can be a hostname

Disabled: when the variable "proxy_mode" hasn't the value "Automatic proxy configuration URL"
no_proxy
domainname multiple disabled unique		Address for which proxy will be desactivated.
Connections to localhost, 127.0.0.1/8 and ::1 are never proxied.
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"
.. note:: The help section serves as supplementary documentation regarding the description parameter and can be used in the various command-line tools that will have to deal with the variable when the `--help` option is called .. 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