90 lines
3.6 KiB
ReStructuredText
90 lines
3.6 KiB
ReStructuredText
Modes
|
||
=========
|
||
|
||
.. objectives:: Objectives
|
||
|
||
For information on the concept we will be using in this section, please refer to
|
||
the definition of the :term:`mode` in the documentation,
|
||
and you can read all the :ref:`description of the modes in the structuring data point of view <structured_data_mode>`.
|
||
|
||
.. 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 tag :tutorial:`v1.1_150 <src/tag/v1.1_150/README.md>`
|
||
in the repository.
|
||
|
||
::
|
||
|
||
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
||
git switch --detach v1.1_150
|
||
|
||
A variable in avanced mode
|
||
---------------------------
|
||
|
||
To specify the various possible modes, we must declare them on the command line
|
||
with the `--modes_level` command line option:
|
||
|
||
.. raw:: html
|
||
:class: terminal
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_150/config/01/cmd_ro.txt
|
||
|
||
..
|
||
rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/01/config.yml
|
||
|
||
|
||
Next, we can set a mode parameter with a value from the list: `basic`, `standard`, `advanced`.
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_150/firefox/55-proxy_dns_socks5.yml
|
||
:language: yaml
|
||
:caption: The `proxy_dns_socks5` variable in the :file:`firefox/55-proxy_dns_socks5.yml` file
|
||
|
||
..
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
proxy_dns_socks5:
|
||
description: Use proxy DNS when using SOCKS v5
|
||
mode: advanced
|
||
default: false
|
||
disabled:
|
||
jinja: |-
|
||
{{ _.manual.socks_proxy.version is propertyerror or _.manual.socks_proxy.version == 'v4' }}
|
||
return_type: boolean
|
||
description: |-
|
||
if "_.manual.socks_proxy.version" is accessible and equals "v4"
|
||
...
|
||
|
||
Here, we have set the mode to `advanced` for the `proxy_dns_socks5` variable
|
||
because we want to classify it as a variable intended for use by advanced users.
|
||
|
||
.. questions:: What is it actually used for?
|
||
|
||
Well, to begin with, reading the structure file provides a clear piece of information:
|
||
this variable is intended to be manipulated by an experienced user.
|
||
|
||
Furthermore, if you integrate Rougail as a library into your business applications,
|
||
you will have access to different types of views corresponding to each mode.
|
||
|
||
A useful application within Rougail itself involves filtering the display of certain
|
||
variables when generating documentation, based on the mode.
|
||
|
||
In our case, this makes it possible to generate documentation for standard users
|
||
where the `proxy_dns_socks5` won't be present,
|
||
and a different, more detailed documentation for advanced users
|
||
where the `proxy_dns_socks5` will be explained in detail.
|
||
|
||
.. seealso:: Look at the :ref:`different ways to document a variable with Rougail <documented_variable>`
|
||
in this tutorial.
|
||
|
||
.. keypoints:: let's review the key points
|
||
|
||
We have seen the benefits of assigning modes to a variable to define
|
||
documentations targeted at specific users.
|