259 lines
15 KiB
ReStructuredText
259 lines
15 KiB
ReStructuredText
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
|
||
|