From dad13466be5f19c232f92cb07c7e069edf57d615 Mon Sep 17 00:00:00 2001 From: gwen Date: Sat, 20 Jun 2026 19:21:09 +0200 Subject: [PATCH] docs(tutorial): modes --- docs/format_content/family.rst | 2 +- docs/structured_data/mode.rst | 37 ++++++++++++++++++++++++++++++++-- docs/tutorial/index.rst | 1 + docs/tutorial/modes.rst | 36 +++++++++++++++++++++++++++++++++ 4 files changed, 73 insertions(+), 3 deletions(-) create mode 100644 docs/tutorial/modes.rst diff --git a/docs/format_content/family.rst b/docs/format_content/family.rst index 9f32c3875..5ff90ac17 100644 --- a/docs/format_content/family.rst +++ b/docs/format_content/family.rst @@ -63,7 +63,7 @@ Parameters **Default value**: The default mode of a family is the smallest mode of the parent families, child variables, or child families that are contained in that family. - .. seealso:: tutorial with a real world sample :doc:`mode parameter <../tutorial/mode>` (the tutorial focuses on variable, but the principle is the same for a family) + .. seealso:: tutorial with a real world sample :doc:`mode parameter <../tutorial/modes>` (the tutorial focuses on variable, but the principle is the same for a family) * - **type**, **_type** diff --git a/docs/structured_data/mode.rst b/docs/structured_data/mode.rst index e108ecb8d..41378320e 100644 --- a/docs/structured_data/mode.rst +++ b/docs/structured_data/mode.rst @@ -1,12 +1,45 @@ Mode ==== -.. index:: mode - By default, the :term:`mode` is not configured. It is an optional feature. +Definition +--------------- + Let's start by defining what we want to do with the :term:`modes `. +.. questions:: What do you mean by "mode"? + + You know, in many applications, in the user interfaces, there are two editing modes: + a basic mode and an advanced mode. + This way, standard users aren't overwhelmed by an overly complex business view, + while domain experts can access more complex views that suit better to their needs. + +We designed this mode concept with that idea in mind. +Of course, it can have a broader meaning, and it is possible to define +much more varied modes (beyond just "basic" or "expert"). + +.. glossary:: + + mode + + At the start of the project, the mode was used to set to variables + some complexity levels. Some variables were seen as "basic", + some other as "normal" (the standard mode) and some variables were seen as "advanced" + (the advanced mode). + + It was a way of classifying the variables as follows: + we could have a view grouping the usual variables (normal mode) + and a view of so-called expert (advanced) variables. + + Regarding variable documentation, we can therefore have + a variables documentation designed for the usual user, + and a variables documentation designed for advanced users. + +Default behavior +------------------ + +By default, the mode is not configured. It is an optional feature. We'll present a common example, but you'll need to define your own :term:`modes ` according to your needs. Here is our classic use case of :term:`mode` definition. We'll use three :term:`modes `: diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index ae90706de..816ae6700 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -62,6 +62,7 @@ Let's dive into this **configuration options validation** use case. document practice1 propertyerror + modes practice2 validators namespace diff --git a/docs/tutorial/modes.rst b/docs/tutorial/modes.rst new file mode 100644 index 000000000..95e07802f --- /dev/null +++ b/docs/tutorial/modes.rst @@ -0,0 +1,36 @@ +Modes +========= + +.. prerequisites:: Prerequisites + + - We assume that Rougail's library is :ref:`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-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 `, + this workshop page corresponds to the tags :tutorial:`v1.1_150 ` to :tutorial:`v1.1_150 ` + 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 +--------------------------- + +on les déclare en CLI `--modes_level basic standard advanced` + +c'est un paramètre à définir sur la famille,  +`mode: advanced` + +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. +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. +C'est quand on était dans l'éditeur Créole, on avait un mode basique (boulet) et une mode expert