141 lines
5.8 KiB
ReStructuredText
141 lines
5.8 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**.
|
||
|
||
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.
|
||
|