[tutorial v1.1_010)] Creating a new family (config and doc)

2025-11-09 19:31:08 +01:00 · 2025-11-09 19:31:08 +01:00 · c99476a564
commit c99476a564
parent 069f24e5a7
17 changed files with 18 additions and 174 deletions
--- a/README.md
+++ b/README.md
@ -1,9 +1,9 @@
 - [Summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/branch/1.1/README.md)
- [[tutorial v1.1_003] Set a default value](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_003/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_003~1..v1.1_003))
+- [[tutorial v1.1_004] Limits the possible values for the variable](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_004/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_004~1..v1.1_004))

-# [tutorial v1.1_004)] Limits the possible values for the variable
+# [tutorial v1.1_010)] Creating a new family

-[View the diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_004~1..v1.1_004)
+[View the diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_010~1..v1.1_010)


 ## Screenshot
@ -29,7 +29,7 @@ pip install rougail-cli rougail-output-exporter rougail-output-doc rougail-user-
 Then switch to the tutorial page:

 ```shell
-git switch --detach v1.1_004
+git switch --detach v1.1_010
 ```

 ## Structure
@ -37,27 +37,22 @@ git switch --detach v1.1_004


 <p>
-<a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_004/./">.</a><br/>
-	└── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_004/./firefox/">firefox</a><br/>
-	    └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_004/./firefox/00-proxy.yml">00-proxy.yml</a><br/>
+<a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_010/./">.</a><br/>
+	└── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_010/./firefox/">firefox</a><br/>
+	    ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_010/./firefox/00-proxy.yml">00-proxy.yml</a><br/>
+	    └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_010/./firefox/10-manual.yml">10-manual.yml</a><br/>
 <br/><br/></p>

-Contents of the firefox/00-proxy.yml file
+Contents of the firefox/10-manual.yml file

 ```yml
 %YAML 1.2
 ---
 version: 1.1

-proxy_mode:
-  description: Configure Proxy Access to the Internet
-  choices:
-    - No proxy
-    - Auto-detect proxy settings for this network
-    - Use system proxy settings
-    - Manual proxy configuration
-    - Automatic proxy configuration URL
-  default: No proxy
+manual:
+  description: Manual proxy configuration
+  type: family
 ...

 ```
@ -70,113 +65,6 @@ rougail -m firefox/ -o doc
 |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | **proxy_mode**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory`                                                                                                                                                                                                                                                                                                                                                                                                                                    | Configure Proxy Access to the Internet.<br/>**Choices**: <br/>- No proxy **← (default)**<br/>- Auto-detect proxy settings for this network<br/>- Use system proxy settings<br/>- Manual proxy configuration<br/>- Automatic proxy configuration URL                                                                                                                                                                                                                                                                                   |

-### Let's generate the changelog
-
-```shell
-rougail -m firefox/ -o doc --doc.contents changelog
-```
-#### Modified variable
-
-| Variable&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   | Description&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   |
-|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **proxy_mode**<br/>~~`string`~~ [<ins>`choice`</ins>](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Configure Proxy Access to the Internet.<br/>**Choices**: <br/>- No proxy **← (default)**<br/>- <ins>Auto-detect proxy settings for this network</ins><br/>- <ins>Use system proxy settings</ins><br/>- <ins>Manual proxy configuration</ins><br/>- <ins>Automatic proxy configuration URL</ins>                                                                                                                                                                                                                                                                                                                                                                                       |


-## User datas
-
-### Example 1
-
-#### config/01/config.yml
-
-
-```yml
---
-```
-#### Output
-
-```shell
-rougail -m firefox/ -u yaml -yf config/01/config.yml
-```
-<pre>╭─────── Caption ────────╮
-│ Variable <span style="color: #ffd700">Default value</span> │
-╰────────────────────────╯
-Variables:
-<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
-</pre>
-### Example 2
-
-#### config/02/config.yml
-
-
-```yml
---
-proxy_mode: No proxy
-```
-#### Output
-
-```shell
-rougail -m firefox/ -u yaml -yf config/02/config.yml
-```
-<pre>╭────────────── Caption ───────────────╮
-│ Variable Modified value              │
-│          (<span style="color: #00aa00">⏳ Original default value</span>) │
-╰──────────────────────────────────────╯
-Variables:
-<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: No proxy ◀ loaded from the YAML file "config/02/config.yml" (⏳ <span style="color: #00aa00">No proxy</span>)
-</pre>
-### Example 3
-
-#### config/03/config.yml
-
-
-```yml
---
-proxy_mode: Manual proxy configuration
-```
-#### Output
-
-```shell
-rougail -m firefox/ -u yaml -yf config/03/config.yml
-```
-<pre>╭────────────── Caption ───────────────╮
-│ Variable Modified value              │
-│          (<span style="color: #00aa00">⏳ Original default value</span>) │
-╰──────────────────────────────────────╯
-Variables:
-<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/03/config.yml" (⏳ <span style="color: #00aa00">No proxy</span>)
-</pre>
-### Example 4
-
-#### config/04/config.yml
-
-
-```yml
---
-proxy_mode: foo
-```
-#### Output
-
-```shell
-rougail -m firefox/ -u yaml -yf config/04/config.yml
-```
-<pre><span style="font-weight: bold; color: #ffff00">🔔 WARNINGS</span>
-<span style="color: #ffff00">┗━━ </span>the value "foo" is an invalid choice for "proxy_mode" (Configure Proxy Access to the Internet), only "Auto-detect proxy settings for this network", "Automatic proxy configuration URL", "Manual proxy 
-<span style="color: #ffff00">    </span>configuration", "No proxy" and "Use system proxy settings" are allowed, it will be ignored when loading from the YAML file "config/04/config.yml"
-╭─────── Caption ────────╮
-│ Variable <span style="color: #ffd700">Default value</span> │
-╰────────────────────────╯
-Variables:
-<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
-</pre>
-#### Output when invalid user datas is an error
-
-```shell
-rougail -m firefox/ -u yaml -yf config/04/config.yml --cli.invalid_user_datas_error
-```
-<pre><span style="font-weight: bold; color: #ff0000">🛑 ERRORS</span>
-<span style="color: #ff0000">┗━━ </span>the value "foo" is an invalid choice for "proxy_mode" (Configure Proxy Access to the Internet), only "Auto-detect proxy settings for this network", "Automatic proxy configuration URL", "Manual proxy 
-<span style="color: #ff0000">    </span>configuration", "No proxy" and "Use system proxy settings" are allowed, it will be ignored when loading from the YAML file "config/04/config.yml"
-</pre>
-
-
- [[tutorial v1.1_010] Creating a new family](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_010/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_010~1..v1.1_010))
+- [[tutorial v1.1_011] Or a sub family](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_011/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_011~1..v1.1_011))
--- a/config/01/cmd_ro.txt
+++ b/config/01/cmd_ro.txt
@ -1 +0,0 @@
-rougail -m firefox/ -u yaml -yf config/01/config.yml
--- a/config/01/config.yml
+++ b/config/01/config.yml
@ -1 +0,0 @@
---
--- a/config/01/output_ro.html
+++ b/config/01/output_ro.html
@ -1,6 +0,0 @@
-<pre>╭─────── Caption ────────╮
-│ Variable <span style="color: #ffd700">Default value</span> │
-╰────────────────────────╯
-Variables:
-<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
-</pre>
--- a/config/02/cmd_ro.txt
+++ b/config/02/cmd_ro.txt
@ -1 +0,0 @@
-rougail -m firefox/ -u yaml -yf config/02/config.yml
--- a/config/02/config.yml
+++ b/config/02/config.yml
@ -1,2 +0,0 @@
---
-proxy_mode: No proxy
--- a/config/02/output_ro.html
+++ b/config/02/output_ro.html
@ -1,7 +0,0 @@
-<pre>╭────────────── Caption ───────────────╮
-│ Variable Modified value              │
-│          (<span style="color: #00aa00">⏳ Original default value</span>) │
-╰──────────────────────────────────────╯
-Variables:
-<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: No proxy ◀ loaded from the YAML file "config/02/config.yml" (⏳ <span style="color: #00aa00">No proxy</span>)
-</pre>
--- a/config/03/cmd_ro.txt
+++ b/config/03/cmd_ro.txt
@ -1 +0,0 @@
-rougail -m firefox/ -u yaml -yf config/03/config.yml
--- a/config/03/config.yml
+++ b/config/03/config.yml
@ -1,2 +0,0 @@
---
-proxy_mode: Manual proxy configuration
--- a/config/03/output_ro.html
+++ b/config/03/output_ro.html
@ -1,7 +0,0 @@
-<pre>╭────────────── Caption ───────────────╮
-│ Variable Modified value              │
-│          (<span style="color: #00aa00">⏳ Original default value</span>) │
-╰──────────────────────────────────────╯
-Variables:
-<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/03/config.yml" (⏳ <span style="color: #00aa00">No proxy</span>)
-</pre>
--- a/config/04/cmd_invalid.txt
+++ b/config/04/cmd_invalid.txt
@ -1 +0,0 @@
-rougail -m firefox/ -u yaml -yf config/04/config.yml --cli.invalid_user_datas_error
--- a/config/04/cmd_ro.txt
+++ b/config/04/cmd_ro.txt
@ -1 +0,0 @@
-rougail -m firefox/ -u yaml -yf config/04/config.yml
--- a/config/04/config.yml
+++ b/config/04/config.yml
@ -1,2 +0,0 @@
---
-proxy_mode: foo
--- a/config/04/output_invalid.html
+++ b/config/04/output_invalid.html
@ -1,4 +0,0 @@
-<pre><span style="font-weight: bold; color: #ff0000">🛑 ERRORS</span>
-<span style="color: #ff0000">┗━━ </span>the value "foo" is an invalid choice for "proxy_mode" (Configure Proxy Access to the Internet), only "Auto-detect proxy settings for this network", "Automatic proxy configuration URL", "Manual proxy 
-<span style="color: #ff0000">    </span>configuration", "No proxy" and "Use system proxy settings" are allowed, it will be ignored when loading from the YAML file "config/04/config.yml"
-</pre>
--- a/config/04/output_ro.html
+++ b/config/04/output_ro.html
@ -1,9 +0,0 @@
-<pre><span style="font-weight: bold; color: #ffff00">🔔 WARNINGS</span>
-<span style="color: #ffff00">┗━━ </span>the value "foo" is an invalid choice for "proxy_mode" (Configure Proxy Access to the Internet), only "Auto-detect proxy settings for this network", "Automatic proxy configuration URL", "Manual proxy 
-<span style="color: #ffff00">    </span>configuration", "No proxy" and "Use system proxy settings" are allowed, it will be ignored when loading from the YAML file "config/04/config.yml"
-╭─────── Caption ────────╮
-│ Variable <span style="color: #ffd700">Default value</span> │
-╰────────────────────────╯
-Variables:
-<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
-</pre>
--- a/firefox.png
+++ b/firefox.png
--- a/tree.html
+++ b/tree.html
@ -25,12 +25,13 @@
 </head>
 <body>
 	<h1>Directory Tree</h1><p>
-	<a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_004/./">.</a><br>
-	└── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_004/./firefox/">firefox</a><br>
-	&nbsp;&nbsp;&nbsp; └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_004/./firefox/00-proxy.yml">00-proxy.yml</a><br>
+	<a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_010/./">.</a><br>
+	└── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_010/./firefox/">firefox</a><br>
+	&nbsp;&nbsp;&nbsp; ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_010/./firefox/00-proxy.yml">00-proxy.yml</a><br>
+	&nbsp;&nbsp;&nbsp; └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_010/./firefox/10-manual.yml">10-manual.yml</a><br>
 <br><br><p>

-2 directories, 1 file
+2 directories, 2 files

 </p>
 	<hr>
				`@ -1 +0,0 @@`
				`rougail -m firefox/ -u yaml -yf config/01/config.yml`