docs(v1.1_121): help string

docs/cli.rst

@@ -142,6 +142,26 @@ Le output doc
 ::
 
     rougail -m structure.yml -o doc --doc.output_format github > README.md 
+::
+
+    doc:
+      Generate documentation from structural files
+
+      -do [{console,asciidoc,html,github,gitlab,json}], --doc.output_format [{console,asciidoc,html,github,gitlab,json}]
+                            The output format of the generated documentation (default: console)
+      -dm [{two_columns,three_columns,four_columns,five_columns,six_columns}], --doc.tabular_template [{two_columns,three_columns,four_columns,five_columns,six_columns}]
+                            Generate document with this tabular model (default: two_columns)
+      -dc {variables,example,changelog} [{variables,example,changelog} ...], --doc.contents {variables,example,changelog} [{variables,example,changelog} ...]
+                            Generated content (default: variables)
+      -dt [TITLE_LEVEL], --doc.title_level [TITLE_LEVEL]
+                            Starting title level (default: 1)
+      --doc.default_values  Modify values to document all variables (default: True)
+      --doc.no-default_values
+      --doc.document_a_type
+                            Documentation a structural type (default: False)
+      --doc.no-document_a_type
+
+
 
 
 Le formatter

docs/tutorial/examples.rst

@@ -70,6 +70,8 @@ Let's give some usage examples of how to use our `no_proxy` variable:
 Here we can see that there are no default values set and as our variable is not :term:`mandatory`, 
 if we don't set values in the user data files as the `no_proxy` variable is :term:`multi`, the `no_proxy` value will be the empty list `[]`:
 
+If we launch the Rougail CLI on user data:
+
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/config.yml
    :language: yaml
    :caption: The :file:`config/03/config.yml` user data file with an `example` parameter but no value set
@@ -78,10 +80,8 @@ if we don't set values in the user data files as the `no_proxy` variable is :ter
     ---
     proxy_mode: Automatic proxy configuration URL
     auto: https://auto.proxy.net/wpad.dat
-    no_proxy:
-      - example.net
-      - 192.168.1.0/24
 
+we can see that the `no_proxy` variable has no user data settings.
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/cmd_ro.txt
@@ -90,6 +90,8 @@ if we don't set values in the user data files as the `no_proxy` variable is :ter
 ..
     rougail -m firefox/ --types types/proxy -u yaml -yf config/01/config.yml
 
+we do indeed obtain the value empty list `[]` for the `no_proxy` variable:
+
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/output_ro.html
    :class: output
@@ -108,10 +110,14 @@ if we don't set values in the user data files as the `no_proxy` variable is :ter
 
 .. type-along:: If we set some user data values 
 
+Just to be thorough, let's look at what happens in a case where there is a value for `no_proxy` entered in the user data file:
+
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/config.yml
    :language: yaml
    :caption: The :file:`config/03/config.yml` user data file with some value set
 
+We launch the Rougail ClI
+
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/cmd_ro.txt
    :class: terminal
@@ -119,6 +125,8 @@ if we don't set values in the user data files as the `no_proxy` variable is :ter
 ..
     rougail -m firefox/ --types types/proxy -u yaml -yf config/02/config.yml
 
+And we have the `no_proxy`'s expected value. No trace in the output of the examples settings of the variable:
+
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/output_ro.html
    :class: output
@@ -137,5 +145,109 @@ if we don't set values in the user data files as the `no_proxy` variable is :ter
         ┣━━ example.net ◀ loaded from the YAML file "config/02/config.yml"
         ┗━━ 192.168.1.0/24 ◀ loaded from the YAML file "config/02/config.yml"
 
-.. note:: In all cases, we can see that none of the values ​​cited in the examples (`.mozilla.org`, `.net.nz`) appear.
+In all cases, we can see that none of the values ​​cited in the examples (`.mozilla.org`, `.net.nz`) appear.
+
+
+.. type-along:: In that case, is there a use for these examples? 
+
+This examples parameter is useful when generating variable documentation. That's where the examples appear.
+
+If we launch the Rougail CLI for the documentation generation:
+
+.. code-block:: bash
+
+   rougail -m firefox --types types/proxy -o doc --doc.output_format html
+
+We have this output:
+
+.. raw:: html
+   :class: output
+
+    <table>
+    <thead>
+    <tr><th>Variable                                                                                                                                                                                               </th><th>Description  </th></tr>
+    </thead>
+    <tbody>
+    <tr><td><b>auto</b><br/><mark><a href='https://rougail.readthedocs.io/en/latest/variable.html#variables-types'>web address</a></mark> <mark>mandatory</mark> <mark><i>disabled</i></mark>                      </td><td>Automatic proxy configuration URL.<br/><b>Validators</b>: <ul><li>well-known ports (1 to 1023) are allowed</li>
+    <li>registred ports (1024 to 49151) are allowed</li>
+    <li>type domainname</li>
+    <li>the domain name can be a hostname</li></ul><br/><b>Disabled</b>: when the variable "proxy_mode" hasn't the value "Automatic proxy configuration URL"              </td></tr>
+    <tr><td><b>no_proxy</b><br/><mark><a href='https://rougail.readthedocs.io/en/latest/variable.html#variables-types'>domainname</a></mark> <mark>multiple</mark> <mark><i>disabled</i></mark> <mark>unique</mark></td><td>Address for which proxy will be desactivated.<br/><b>Validators</b>: <ul><li>type domainname</li>
+    <li>the domain name can starts by a dot</li>
+    <li>the domain name can be a hostname</li>
+    <li>the domain name can be an IP</li>
+    <li>the domain name can be network in CIDR format</li></ul><br/><b>Examples</b>: <ul><li>.mozilla.org</li>
+    <li>.net.nz</li>
+    <li>192.168.1.0/24</li></ul><br/><b>Disabled</b>: when the variable "proxy_mode" has the value "No proxy"              </td></tr>
+    </tbody>
+    </table>
+
+..
+        ├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────┤
+        │ no_proxy                                                                                    │ Address for which proxy will be desactivated.                                                │
+        │  domainname   multiple   disabled   unique                                                  │ Validators:                                                                                  │
+        │                                                                                             │ • type domainname                                                                            │
+        │                                                                                             │ • the domain name can starts by a dot                                                        │
+        │                                                                                             │ • the domain name can be a hostname                                                          │
+        │                                                                                             │ • the domain name can be an IP                                                               │
+        │                                                                                             │ • the domain name can be network in CIDR format                                              │
+        │                                                                                             │ Examples:                                                                                    │
+        │                                                                                             │ • .mozilla.org                                                                               │
+        │                                                                                             │ • .net.nz                                                                                    │
+        │                                                                                             │ • 192.168.1.0/24                                                                             │
+        │                                                                                             │ Disabled: when the variable "proxy_mode" has the value "No proxy"                            │
+        └─────────────────────────────────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────┘
+        
+we can see that this time the examples (`.mozilla.org`, `.net.nz`) appear.
+
+Help
+-------
+
+.. type-along:: For those who follow the tutorial with the help of the git repository
+
+    Now you need to checkout the :tutorial:`v1.1_121 <src/tag/v1.1_121/README.md>` version::
+
+          git switch --detach v1.1_121
+
+Could we define personalized assistance, in the same way that we defined examples?
+
+Yes, very simply: we add a `help` parameter to our `no_proxy` variable: 
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_121/firefox/40-no_proxy.yml
+   :language: yaml
+   :caption: The :file:`firefox/40-no_proxy` structure definition file with an `example` parameter
+
+
+In the same way, this help `"Connections to localhost, 127.0.0.1/8 and ::1 are never proxied"` will appear in the documentation:
+
+.. raw:: html
+   :class: output
+
+    <table>
+    <thead>
+    <tr><th>Variable                                                                                                                                                                                               </th><th>Description  </th></tr>
+    </thead>
+    <tbody>
+    <tr><td><b>auto</b><br/><mark><a href='https://rougail.readthedocs.io/en/latest/variable.html#variables-types'>web address</a></mark> <mark>mandatory</mark> <mark><i>disabled</i></mark>                      </td><td>Automatic proxy configuration URL.<br/><b>Validators</b>: <ul><li>well-known ports (1 to 1023) are allowed</li>
+    <li>registred ports (1024 to 49151) are allowed</li>
+    <li>type domainname</li>
+    <li>the domain name can be a hostname</li></ul><br/><b>Disabled</b>: when the variable "proxy_mode" hasn't the value "Automatic proxy configuration URL"              </td></tr>
+    <tr><td><b>no_proxy</b><br/><mark><a href='https://rougail.readthedocs.io/en/latest/variable.html#variables-types'>domainname</a></mark> <mark>multiple</mark> <mark><i>disabled</i></mark> <mark>unique</mark></td><td>Address for which proxy will be desactivated.<br/>Connections to localhost, 127.0.0.1/8 and ::1 are never proxied.<br/><b>Validators</b>: <ul><li>type domainname</li>
+    <li>the domain name can starts by a dot</li>
+    <li>the domain name can be a hostname</li>
+    <li>the domain name can be an IP</li>
+    <li>the domain name can be network in CIDR format</li></ul><br/><b>Examples</b>: <ul><li>.mozilla.org</li>
+    <li>.net.nz</li>
+    <li>192.168.1.0/24</li></ul><br/><b>Disabled</b>: when the variable "proxy_mode" has the value "No proxy"              </td></tr>
+    </tbody>
+    </table>
+ 
+
+
+
+
+.. keypoints:: Key points
+
+   - We have seen how to give examples, simply with the `examples` parameter
+   - We have seen how to specify a help, simply with the `help` parameter