From eda0632809b383f1057ba40037eae102f0645180 Mon Sep 17 00:00:00 2001 From: gwen Date: Mon, 28 Oct 2024 15:29:11 +0100 Subject: [PATCH] missign rougail-tutorial tags --- docs/gettingstarted.rst | 33 ++++++++++--- docs/tutorial/preliminary.rst | 93 +++++++++++++++++++++++++++++------ 2 files changed, 104 insertions(+), 22 deletions(-) diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index f356ef606..2f9ef20cc 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -71,13 +71,18 @@ Before getting started with Rougail we need to learn the specifics of the YAML d Here is an empty rougail dictionary YAML file -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_001/firefox/00-proxy.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml :linenos: :language: yaml :caption: An empty rougail dictionnary file. It's a YAML format. :name: RougailDictionaryEmptyFile -:download:`source file ` +.. + --- + version: 1.1 + + +:download:`source file ` You can see that there is just a `version` specification. @@ -100,34 +105,48 @@ The variables Here is a :term:`structure file ` example with a variable into it: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/firefox/00-proxy.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`. It's the Rougail YAML dictionary format. :name: RougailDictionaryFirstVariable -:download:`source file ` +.. + --- + proxy_mode: + +:download:`source file ` Here we declare a **variable** named `proxy_mode` without a default value. A variable can be defined with no default value at all. Here is the same variable with a description label: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a description. :name: RougailDictionaryFirstVariableDescription +.. + --- + proxy_mode: + description: Configure Proxy Access to the Internet + The same with a default value: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_005/firefox/00-proxy.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/00-proxy.yml :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value. :name: RougailDictionaryFirstVariableDefault +.. + --- + proxy_mode: + description: Configure Proxy Access to the Internet + default: No proxy + variable A variable is a declaration unit that represents a business domain metaphor, diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 3dc58c915..c7fcfdbee 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -83,11 +83,15 @@ So, if : - there is no default value set in the structure file, - no value is set in the value file: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml :linenos: :language: yaml - :caption: The :file:`config/01/config.yaml` rougail dictionnary file, with no default value set. - :name: RougailDictionaryNoDefaultUseCase + :caption: The :file:`struct/config.yaml` rougail structure file, with no default value set. + :name: RougailDictionaryNoDefault + +.. + --- + proxy_mode: In this situation there are no default value set. The rougail CLI will output an error : @@ -97,8 +101,15 @@ In this situation there are no default value set. The rougail CLI will output an foo@bar:~$ rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/01/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_010/config/01/output_ro.html +.. + 
🛑 ERRORS
+    ┣━━ The following variables are mandatory but have no value:
+    ┗━━   - proxy_mode
+
+ +.. important:: Once defined, an option configuration :term:`value` is :term:`mandatory`. Rougail waits for a value to be set, that's why. @@ -107,17 +118,54 @@ Rougail waits for a value to be set, that's why. Type inference ----------------- -By default, rougail infers a `string` type for the `proxy_mode` configuration option variable type. -If the operator sets an option value with the `string` type, like this: +By default, rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined +in the structure file. +. +If the operator sets an option value for example with the `number` type, like this: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/05/config.yaml +.. code-block:: yaml + + --- + example_var: + description: Configure Proxy Access to the Internet + type: number + +Then rougail will expect a `int` or a `float` as a value for the `example_var` variable. +In our firefox use case, the real type of the `proxy_mode` variable is a `choice` type: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_013/config/05/config.yaml :linenos: :language: yaml - :caption: The :file:`config/05/config.yaml` rougail dictionnary file, with no default value set. - :name: RougailDictionaryNoDefaultUseCaseIntOptionValue + :caption: The :file:`config/05/config.yaml` rougail dictionnary file, with a default value set. + :name: RougailDictionaryChoiceTypeWitheDefault + +.. + --- + proxy_mode: + description: Configure Proxy Access to the Internet + type: choice + choices: + - No proxy + - Auto-detect proxy settings for this network + - Use system proxy settings + - Manual proxy configuration + - Automatic proxy configuration URL + default: No proxy .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/05/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_013/config/01/output_ro.html + +.. + 
╭────────────────────────── Caption ──────────────────────────╮
+    │ Variable                           Default value            │
+    │ Undocumented variable              Modified value           │
+    │ Undocumented but modified variable (Original default value) │
+    │ Unmodifiable variable                                       │
+    ╰─────────────────────────────────────────────────────────────╯
+    Variables:
+    ┗━━ 📓 proxy_mode: No proxy
+
+ .. keypoints:: Key points progress @@ -126,18 +174,33 @@ If the operator sets an option value with the `string` type, like this: - :term:`structure file `: structure description file - :term:`variable`: an option's name which has a value - a variable's description + - a variable's type - a variable's default value - the :term:`integrator` and :term:`operator` roles - - a mandatory option value + - a mandatory value - - To sum up, we have arrived here + To sum up, we have arrived at this point in writing the structure file: **Structure description file** - .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_005/firefox/00-proxy.yml + .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value. - :name: RougailDictionaryDefaultVariabletUseCase + +.. + + .. raw:: text + + --- + proxy_mode: + description: Configure Proxy Access to the Internet + type: choice + choices: + - No proxy + - Auto-detect proxy settings for this network + - Use system proxy settings + - Manual proxy configuration + - Automatic proxy configuration URL + default: No proxy