docs(tutorial): modes
ready for proofreading
This commit is contained in:
gwen
parent
dad13466be
commit
ebdeeec3af
4 changed files with 67 additions and 13 deletions
|
|
@ -50,11 +50,7 @@ The `auto_freeze` property is only applied until a specific variable becomes `Tr
|
||||||
Modes
|
Modes
|
||||||
~~~~~~~~
|
~~~~~~~~
|
||||||
|
|
||||||
.. glossary::
|
A mode is a solution that allows a variable or a family to be categorized. It can be used, for example, to define a level of expertise or a particular context. Have a look at the :term:`mode definition <mode>` for further details.
|
||||||
|
|
||||||
mode
|
|
||||||
|
|
||||||
A mode is a solution that allows a variable or a family to be categorized. It can be used, for example, to define a level of expertise or a particular context.
|
|
||||||
|
|
||||||
Modes are customizable in Rougail.
|
Modes are customizable in Rougail.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,3 +1,5 @@
|
||||||
|
.. _structured_data_mode:
|
||||||
|
|
||||||
Mode
|
Mode
|
||||||
====
|
====
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,3 +1,5 @@
|
||||||
|
.. _documented_variable:
|
||||||
|
|
||||||
A full documented variable
|
A full documented variable
|
||||||
==============================
|
==============================
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,12 @@
|
||||||
Modes
|
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
|
.. prerequisites:: Prerequisites
|
||||||
|
|
||||||
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
||||||
|
|
@ -22,15 +28,63 @@ Modes
|
||||||
A variable in avanced mode
|
A variable in avanced mode
|
||||||
---------------------------
|
---------------------------
|
||||||
|
|
||||||
on les déclare en CLI `--modes_level basic standard advanced`
|
To specify the various possible modes, we must declare them on the command line
|
||||||
|
with the `--modes_level` command line option:
|
||||||
|
|
||||||
c'est un paramètre à définir sur la famille,
|
.. raw:: html
|
||||||
`mode: advanced`
|
:class: terminal
|
||||||
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_150/config/01/cmd_ro.txt
|
||||||
|
|
||||||
aujourd'hui je m'en sert pour filtrer les variables que je veux dans ma doc
|
..
|
||||||
Une doc sans les variables avancées qui sera plus courte et une seconde complète.
|
rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/01/config.yml
|
||||||
Tu peux expliquer comme ça et on réfléchira au concept plus tard.
|
|
||||||
|
|
||||||
|
|
||||||
à part ça je ne me souviens pas bien de l'usage à l'époque de créole.
|
Next, we can set a mode parameter with a value from the list: `basic`, `standard`, `advanced`.
|
||||||
C'est quand on était dans l'éditeur Créole, on avait un mode basique (boulet) et une mode expert
|
|
||||||
|
.. 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.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue