proxy mode tutorial

2025-02-20 14:23:34 +01:00 · 2025-02-20 14:23:34 +01:00 · 9ca27d7f51
commit 9ca27d7f51
parent 2d39fe8bad
6 changed files with 65 additions and 36 deletions
--- 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
--- 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.
--- 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

--- 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
--- 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<structure 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 <structure file>` 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 <structure 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 <value>` to the :confval:`adress` variable
+The :term:`operator` can now then set :term:`a value <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 <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`. 
--- 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`.