From 9ca27d7f51a1bb1c4fe169c119c1b466d29fe7f2 Mon Sep 17 00:00:00 2001 From: gwen Date: Thu, 20 Feb 2025 14:23:34 +0100 Subject: [PATCH] proxy mode tutorial --- docs/Makefile | 1 + docs/family.rst | 1 - docs/gettingstarted.rst | 2 +- docs/tutorial/preliminary.rst | 1 - docs/tutorial/proxymode.rst | 95 +++++++++++++++++++++++------------ docs/variable.rst | 1 - 6 files changed, 65 insertions(+), 36 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index ed8809902..b40d9f982 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -18,3 +18,4 @@ help: # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + ./mistergwen.sh diff --git a/docs/family.rst b/docs/family.rst index 4c5fdefe0..b4f9044b9 100644 --- a/docs/family.rst +++ b/docs/family.rst @@ -7,7 +7,6 @@ Synopsis .. glossary:: family - families A family of variables is simply a collection of variables that refer to the same business model category. It's just a variables container. diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 9a90a7dbc..edb34d3f4 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -6,7 +6,7 @@ Getting started Installation ---------------- -You just have to type this in your preferred terminal: +You can use the python installer and type the install command in your preferred terminal: .. code-block:: text diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 324b42bf9..98dd930aa 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -233,7 +233,6 @@ In our firefox use case, the real type of the `proxy_mode` variable will be now A choice type variable is a variable where the content is constrained by a list - .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml :linenos: :language: yaml diff --git a/docs/tutorial/proxymode.rst b/docs/tutorial/proxymode.rst index ce4ff4a6b..ebbaf6511 100644 --- a/docs/tutorial/proxymode.rst +++ b/docs/tutorial/proxymode.rst @@ -1,30 +1,64 @@ The `proxy` family ==================== - .. objectives:: Objectives We will learn how to: - create a :term:`family` - - gather variables into a family - - make a variable in a variable, which is a family too + - gather :term:`variable`\ s into a :term:`family` + - make a variable within a variable, which turns this variable container into being a family + +.. prerequisites:: Reminders + + - We have an idea of what a :term:`structure description file` is + - We have a folder named :file:`firefox` and we are putting all the structure description files into it -.. type-along:: Reminders +.. type-along:: So we have this choice type variable in the structure file - - As a prerequisite we have an idea of what a :term:`structure file description ` is. - - We have a :file:`firefox` folder and we are putting all the structure description files in it. - - We had at the :term:`structure description file ` - -A `manual` family --------------------- - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml :linenos: :language: yaml - :caption: A family structure file description named `manual` in the :file:`firefox/10-manual.yml` file - :name: RougailFirstDictionary + :caption: The `proxy_mode` choice type variable in the :file:`firefox/00-proxy.yml` structure file + +.. + --- + 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 + +.. We're gonna put it in a :term:`family`. + +.. note:: The variables, families, etc. will be created in several files for educational purposes. + Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make + a new structure file named :file:`firefox/10-manual.yml` + We could of course have put everything in one file, we decided to separate the files for reasons of ordering and clarity + +So we have now a `proxy_mode` variable. + +.. confval:: proxy_mode + :type: `choice` + :default: No proxy + + This is a setting that controls the proxy's type + +A family named `manual` +------------------------- + +Let's create a family named `manual` + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml + :language: yaml + :caption: A family structure file description named `manual` in a :file:`firefox/10-manual.yml` file + :name: RougailManualFamily .. --- @@ -33,26 +67,21 @@ A `manual` family type: family We can see that we have defined a :term:`family` here, and this family is *empty* -(that is, the family container contains no variable yet). +(that is the family which is a container variable contains no variable yet). .. admonition:: If a family is empty We need to specify the :term:`family` type here because if we don't, the Rougail's type engine will infer it by default as a :term:`variable`. -It's because we don't have set any :term:`variable` inside. If we make a YAML block -(that is, if we indent), the Rougail's type inference engine will implicitely make it a family. + It's because we don't have set any :term:`variable` inside. If we have a variable inside of a family, + we make a YAML block (that is, we indent) and the Rougail's type inference engine will implicitely infer it as a family. -.. note:: The variables, families, etc. will be created in several files for educational purposes. - Obviously all the variables can be put in the same file. +.. type-along:: A family inside a family -A family inside a family ----------------------------- - -Creating a family hierarchy is very easy, here is an example +Creating a family hierarchy is very easy, here is an example: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml - :linenos: :language: yaml :caption: A rougail structure description file with a hierarchy. :name: RougailFirstFamilyHierarchy @@ -69,14 +98,13 @@ Creating a family hierarchy is very easy, here is an example Here the `http_proxy` family lives inside the `manual` family. -Put a variable inside a family or a sub family --------------------------------------------------- +Putting a variable inside of a family or a sub family +---------------------------------------------------------- -Let's create a variable in its family with a description and a default value. +Let's create a variable in its family. The type of this variable is a `choice` type: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/firefox/10-manual.yml - :linenos: +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/firefox/10-manual.yml :language: yaml :caption: An `address` variable in the `http_proxy` family :name: RougailVariableInSubFamily @@ -93,9 +121,11 @@ The type of this variable is a `choice` type: address: description: HTTP address + type: domainname -The :term:`operator` can then set :term:`a value ` to the :confval:`adress` variable +The :term:`operator` can now then set :term:`a value ` to the :confval:`address` variable +So we have now an `address` variable. .. confval:: address :type: `string` (a *domain name*) @@ -103,10 +133,11 @@ The :term:`operator` can then set :term:`a value ` to the :confval:`adres This is a setting that controls the value of the answer. - .. keypoints:: Key points progress **Keywords** - :term:`family`, and sub families - - variables defined in a family + - :term:`variable`\ s defined inside of a family + +We have two variables :confval:`proxy_mode` and :confval:`address`. diff --git a/docs/variable.rst b/docs/variable.rst index 62c3286d8..d02fdac8c 100644 --- a/docs/variable.rst +++ b/docs/variable.rst @@ -7,7 +7,6 @@ Synopsis .. glossary:: variable - variables A variable is an abstract black box (container) paired with an associated symbolic name, wmost often an option configuration, hich contains some defined or undefined data setting referred to as a :term:`value`.