A full documented variable
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
We assume that Rougail’s library is 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-tutorialsgit 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 rougail-tutorials git repository, this workshop page corresponds to the tags v1.1_120 to 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:
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:
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.
We do indeed obtain the value empty list [] for the no_proxy variable:
╭────────────── Caption ───────────────╮ │ Variable Default value │ │ Modified value │ │ (⏳ Original default value) │ ╰──────────────────────────────────────╯ Variables: ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): Automatic proxy ┃ configuration URL ◀ loaded from the YAML file "config/03/config.yml" (⏳ No ┃ proxy) ┣━━ 📓 auto (Automatic proxy configuration URL): https://auto.proxy.net/wpad.dat ┃ ◀ loaded from the YAML file "config/03/config.yml" ┗━━ 📓 no_proxy (Address for which proxy will be desactivated): []
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:
config/03/config.yml user data file with some value set---
proxy_mode: Automatic proxy configuration URL
auto: https://auto.proxy.net/wpad.dat
no_proxy:
- example.net
- 192.168.1.0/24
We launch the Rougail CLI:
And we have the no_proxy’s expected value. No trace in the output of the examples settings of the variable:
╭────────────── Caption ───────────────╮ │ Variable Modified value │ │ (⏳ Original default value) │ ╰──────────────────────────────────────╯ Variables: ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): Automatic proxy ┃ configuration URL ◀ loaded from the YAML file "config/02/config.yml" (⏳ No ┃ proxy) ┣━━ 📓 auto (Automatic proxy configuration URL): https://auto.proxy.net/wpad.dat ┃ ◀ loaded from the YAML file "config/02/config.yml" ┗━━ 📓 no_proxy (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.
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:
rougail -m firefox --types types/proxy -o doc --doc.output_format html
We have this output:
| Variable | Description |
|---|---|
| auto web address mandatory disabled | Automatic proxy configuration URL. Validators:
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:
Examples:
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
For those who follow the tutorial with the help of the git repository
Now you need to checkout the 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:
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
help: Connections to localhost, 127.0.0.1/8 and ::1 are never proxied
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
...
In the same way, this help "Connections to localhost, 127.0.0.1/8 and ::1 are never proxied" will appear in the documentation:
| Variable | Description |
|---|---|
| auto web address mandatory disabled | Automatic proxy configuration URL. Validators:
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:
Examples:
Disabled: when the variable "proxy_mode" has the value "No proxy" |
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 description parameter and the help parameter’s variable usage.
A 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 help helps to clarify any ambiguity about the variable’s purpose. It can be long and detailed.
Key points
We have seen how to give examples, simply with the
examplesparameterWe have seen how to specify a help, simply with the
helpparameter