rougail-tutorials/README.md

316 lines
27 KiB
Markdown
Raw Normal View History

- [Summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/branch/1.1/README.md)
- [[tutorial v1.1_180] Regexp type](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_180/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_181~1..v1.1_181))
# [tutorial v1.1_181] Calculate a random color
[Read the tutorial "Calculate a random color" in the documentation](https://pedago.gwenaelremond.fr/bribes/rougail/tutorial/jinja.html#calculate-a-random-color)
2026-03-12 08:10:13 +01:00
## Screenshot
<img src="foxyproxy.png" width=50% height=50% alt="Firefox Proxy setting"/>
2026-03-12 08:10:13 +01:00
## Clone and install
To test this tutorial, you need to download this repository and install Rougail:
```shell
git clone -b 1.1 https://forge.cloud.silique.fr/stove/rougail-tutorials.git
cd rougail-tutorials
python -m venv venv_rougail
. venv_rougail/bin/activate
pip install rougail-cli rougail-output-exporter rougail-output-doc rougail-user-data-yaml
```
Then switch to the tutorial page:
```shell
git switch --detach v1.1_181
2026-03-12 08:10:13 +01:00
```
## Structure
<p>
<a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./">.</a><br/>
├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./firefox/">firefox</a><br/>
│   ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./firefox/00-proxy.yml">00-proxy.yml</a><br/>
│   ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./firefox/10-manual.yml">10-manual.yml</a><br/>
│   ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./firefox/20-manual.yml">20-manual.yml</a><br/>
│   ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./firefox/30-auto.yml">30-auto.yml</a><br/>
│   ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./firefox/40-no_proxy.yml">40-no_proxy.yml</a><br/>
│   ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./firefox/50-prompt_authentication.yml">50-prompt_authentication.yml</a><br/>
│   ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./firefox/55-proxy_dns_socks5.yml">55-proxy_dns_socks5.yml</a><br/>
│   └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./firefox/60-dns_over_https.yml">60-dns_over_https.yml</a><br/>
├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./foxyproxy/">foxyproxy</a><br/>
│   └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./foxyproxy/00-foxyproxy.yml">00-foxyproxy.yml</a><br/>
└── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./types/">types</a><br/>
    └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./types/proxy/">proxy</a><br/>
        └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_181/./types/proxy/00_type.yml">00_type.yml</a><br/>
<br/><br/></p>
Contents of the foxyproxy/00-foxyproxy.yml file
```yml
%YAML 1.2
---
version: 1.1
proxies:
description: Proxy configuration
type: leadership
title:
description: Title or Description
mandatory: false
color:
description: Color
regexp: ^#(?:[0-9a-f]{3}){1,2}$
default:
jinja: >-
#{%- for i in range(6) -%}{{- '0123456789abcdef' | random -}}{%- endfor -%}
description: random color value
...
```
***
### Let's generate the documentation
```shell
rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -o doc
```
#### Firefox
> [!NOTE]
>
> This family is a namespace.\
> **Path**: firefox\
> `basic`
| Variable | Description |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.proxy_mode" name="firefox.proxy_mode">firefox.proxy_mode</a>**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Configure Proxy Access to the Internet.<br/>**Choices**: <br/>&nbsp;No proxy **← (default)**<br/>&nbsp;Auto-detect proxy settings for this network<br/>&nbsp;Use system proxy settings<br/>&nbsp;Manual proxy configuration<br/>&nbsp;Automatic proxy configuration URL |
##### Manual proxy configuration
> [!NOTE]
>
> **Path**: firefox.manual\
> `basic` *`disabled`*\
> **Disabled**: when the variable "[Configure Proxy Access to the Internet](#firefox.proxy_mode)" hasn't the value "Manual proxy configuration"
###### HTTP Proxy
> [!NOTE]
>
> **Path**: firefox.manual.http_proxy\
> `basic`
| Variable | Description |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.manual.http_proxy.address" name="firefox.manual.http_proxy.address">firefox.manual.http_proxy.address</a>**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `basic` `mandatory` | Proxy address.<br/>**Validators**: <br/>&nbsp;type domainname<br/>&nbsp;the domain name can be an IP |
| **<a id="firefox.manual.http_proxy.port" name="firefox.manual.http_proxy.port">firefox.manual.http_proxy.port</a>**<br/>[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy port.<br/>**Validators**: <br/>&nbsp;well-known ports (1 to 1023) are allowed<br/>&nbsp;registred ports (1024 to 49151) are allowed<br/>&nbsp;private ports (greater than 49152) are allowed<br/>**Default**: 8080 |
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
| **<a id="firefox.manual.use_for_https" name="firefox.manual.use_for_https">firefox.manual.use_for_https</a>**<br/>[`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Also use this proxy for HTTPS.<br/>**Default**: true |
###### HTTPS Proxy
> [!NOTE]
>
> **Path**: firefox.manual.https_proxy\
> `standard` *`hidden`*\
> **Hidden**: when the variable "[Also use this proxy for HTTPS](#firefox.manual.use_for_https)" has the value "true"
| Variable | Description |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.manual.https_proxy.address" name="firefox.manual.https_proxy.address">firefox.manual.https_proxy.address</a>**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy address.<br/>**Validators**: <br/>&nbsp;type domainname<br/>&nbsp;the domain name can be an IP<br/>**Default**: the value of the variable "[Proxy address](#firefox.manual.http_proxy.address)" |
| **<a id="firefox.manual.https_proxy.port" name="firefox.manual.https_proxy.port">firefox.manual.https_proxy.port</a>**<br/>[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy port.<br/>**Validators**: <br/>&nbsp;well-known ports (1 to 1023) are allowed<br/>&nbsp;registred ports (1024 to 49151) are allowed<br/>&nbsp;private ports (greater than 49152) are allowed<br/>**Default**: the value of the variable "[Proxy port](#firefox.manual.http_proxy.port)" |
###### SOCKS Proxy
> [!NOTE]
>
> **Path**: firefox.manual.socks_proxy\
> `standard`
| Variable | Description |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.manual.socks_proxy.address" name="firefox.manual.socks_proxy.address">firefox.manual.socks_proxy.address</a>**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy address.<br/>**Validators**: <br/>&nbsp;type domainname<br/>&nbsp;the domain name can be an IP<br/>**Default**: the value of the variable "[Proxy address](#firefox.manual.http_proxy.address)" |
| **<a id="firefox.manual.socks_proxy.port" name="firefox.manual.socks_proxy.port">firefox.manual.socks_proxy.port</a>**<br/>[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy port.<br/>**Validators**: <br/>&nbsp;well-known ports (1 to 1023) are allowed<br/>&nbsp;registred ports (1024 to 49151) are allowed<br/>&nbsp;private ports (greater than 49152) are allowed<br/>**Default**: the value of the variable "[Proxy port](#firefox.manual.http_proxy.port)" |
| **<a id="firefox.manual.socks_proxy.version" name="firefox.manual.socks_proxy.version">firefox.manual.socks_proxy.version</a>**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | SOCKS host version used by proxy.<br/>**Choices**: <br/>&nbsp;v4<br/>&nbsp;v5 **← (default)** |
| Variable | Description |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.auto" name="firefox.auto">firefox.auto</a>**<br/>[`web address`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `basic` `mandatory` *`disabled`* | Automatic proxy configuration URL.<br/>**Validators**: <br/>&nbsp;well-known ports (1 to 1023) are allowed<br/>&nbsp;registred ports (1024 to 49151) are allowed<br/>&nbsp;type domainname<br/>&nbsp;the domain name can be a hostname<br/>**Disabled**: when the variable "[Configure Proxy Access to the Internet](#firefox.proxy_mode)" hasn't the value "Automatic proxy configuration URL" |
| **<a id="firefox.no_proxy" name="firefox.no_proxy">firefox.no_proxy</a>**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` `standard` *`disabled`* `unique` | Address for which proxy will be desactivated.<br/>Connections to localhost, 127.0.0.1/8 and ::1 are never proxied.<br/>**Validators**: <br/>&nbsp;type domainname<br/>&nbsp;the domain name can starts by a dot<br/>&nbsp;the domain name can be a hostname<br/>&nbsp;the domain name can be an IP<br/>&nbsp;the domain name can be network in CIDR format<br/>**Examples**: <br/>&nbsp;.mozilla.org<br/>&nbsp;.net.nz<br/>&nbsp;192.168.1.0/24<br/>**Disabled**: when the variable "[Configure Proxy Access to the Internet](#firefox.proxy_mode)" has the value "No proxy" |
| **<a id="firefox.prompt_authentication" name="firefox.prompt_authentication">firefox.prompt_authentication</a>**<br/>[`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` *`disabled`* | Prompt for authentication if password is saved.<br/>**Default**: true<br/>**Disabled**: when the variable "[Configure Proxy Access to the Internet](#firefox.proxy_mode)" has the value "No proxy" |
| **<a id="firefox.proxy_dns_socks5" name="firefox.proxy_dns_socks5">firefox.proxy_dns_socks5</a>**<br/>[`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `advanced` `mandatory` *`disabled`* | Use proxy DNS when using SOCKS v5.<br/>**Default**: false<br/>**Disabled**: if "[Configure Proxy Access to the Internet](#firefox.proxy_mode)" is not "Manual proxy configuration"<br/>or "[SOCKS host version used by proxy](#firefox.manual.socks_proxy.version)" is "v4" |
##### DNS over HTTPS
> [!NOTE]
>
> **Path**: firefox.dns_over_https\
> `basic`
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.dns_over_https.enable_dns_over_https" name="firefox.dns_over_https.enable_dns_over_https">firefox.dns_over_https.enable_dns_over_https</a>**<br/>[`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Enable DNS over HTTPS.<br/>**Default**: false |
| **<a id="firefox.dns_over_https.provider" name="firefox.dns_over_https.provider">firefox.dns_over_https.provider</a>**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` *`disabled`* | Use Provider.<br/>**Choices**: <br/>&nbsp;Cloudflare **← (default)**<br/>&nbsp;NextDNS<br/>&nbsp;Custom<br/>**Disabled**: when the variable "[Enable DNS over HTTPS](#firefox.dns_over_https.enable_dns_over_https)" has the value "false" |
| **<a id="firefox.dns_over_https.custom_dns_url" name="firefox.dns_over_https.custom_dns_url">firefox.dns_over_https.custom_dns_url</a>**<br/>[`web address`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `basic` `mandatory` *`disabled`* | Custom DNS URL.<br/>**Validators**: <br/>&nbsp;well-known ports (1 to 1023) are allowed<br/>&nbsp;registred ports (1024 to 49151) are allowed<br/>&nbsp;type domainname<br/>&nbsp;the domain name can be a hostname<br/>&nbsp;must starts with 'https://' only<br/>**Disabled**: if "[Use Provider](#firefox.dns_over_https.provider)" is not "Custom" |
#### FoxyProxy
> [!NOTE]
>
> This family is a namespace.\
> **Path**: foxyproxy\
> `standard`
##### Proxy configuration
> [!NOTE]
>
> This family contains lists of variable blocks.\
> **Path**: foxyproxy.proxies\
> `standard`
| Variable | Description |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| **<a id="foxyproxy.proxies.title" name="foxyproxy.proxies.title">foxyproxy.proxies.title</a>**<br/>[`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` `standard` `unique` | Title or Description. |
| **<a id="foxyproxy.proxies.color" name="foxyproxy.proxies.color">foxyproxy.proxies.color</a>**<br/>[`regexp`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Color.<br/>**Validator**: text based with regular expressions "^#(?:[0-9a-f]{3}){1,2}$"<br/>**Default**: random color value |
***
### Let's generate the changelog
```shell
rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -o doc --doc.contents changelog --doc.changelog.previous_json_file previous.yml
```
#### Modified variable
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="foxyproxy.proxies.color" name="foxyproxy.proxies.color">foxyproxy.proxies.color</a>**<br/>~~`basic`~~ <ins>`standard`</ins> [`regexp`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Color.<br/>**Validator**: text based with regular expressions "^#(?:[0-9a-f]{3}){1,2}$"<br/>**Default**: <ins>random color value</ins> |
***
## User datas
### Example 1
#### config/01/config.yml
```yml
---
```
***
#### Output
```shell
rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/01/config.yml
```
> [!NOTE]
>
> **Caption:**
> - Variable
> - <span style="color: #B8860B">Default value</span>
Variables:
- :open_file_folder: firefox (Firefox)
- :notebook: proxy_mode (Configure Proxy Access to the Internet): <span style="color: #B8860B">No proxy</span>
- :open_file_folder: dns_over_https (DNS over HTTPS)
- :notebook: enable_dns_over_https (Enable DNS over HTTPS): <span style="color: #B8860B">false</span>
- :open_file_folder: foxyproxy (FoxyProxy)
- :open_file_folder: proxies (Proxy configuration): <span style="color: #B8860B">[]</span>
***
### Example 2
#### config/02/config.yml
```yml
---
foxyproxy:
proxies:
- title: My company
```
***
#### Output
```shell
rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/02/config.yml
```
> [!NOTE]
>
> **Caption:**
> - Variable
> - <span style="color: #B8860B">Default value</span>
> - <span style="color: #006400">Modified value</span>
Variables:
- :open_file_folder: firefox (Firefox)
- :notebook: proxy_mode (Configure Proxy Access to the Internet): <span style="color: #B8860B">No proxy</span>
- :open_file_folder: dns_over_https (DNS over HTTPS)
- :notebook: enable_dns_over_https (Enable DNS over HTTPS): <span style="color: #B8860B">false</span>
- :open_file_folder: foxyproxy (FoxyProxy)
- :open_file_folder: proxies (Proxy configuration)
- :open_file_folder: title (Title or Description)
- :notebook: title (Title or Description): <span style="color: #006400">My company</span> ← loaded from the YAML file "config/02/config.yml"
- :notebook: color (Color): <span style="color: #B8860B">#00f139</span>
***
### Example 3
#### config/03/config.yml
```yml
---
foxyproxy:
proxies:
- title: My company
```
***
#### Output
```shell
rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/03/config.yml
```
> [!NOTE]
>
> **Caption:**
> - Variable
> - <span style="color: #B8860B">Default value</span>
> - <span style="color: #006400">Modified value</span>
Variables:
- :open_file_folder: firefox (Firefox)
- :notebook: proxy_mode (Configure Proxy Access to the Internet): <span style="color: #B8860B">No proxy</span>
- :open_file_folder: dns_over_https (DNS over HTTPS)
- :notebook: enable_dns_over_https (Enable DNS over HTTPS): <span style="color: #B8860B">false</span>
- :open_file_folder: foxyproxy (FoxyProxy)
- :open_file_folder: proxies (Proxy configuration)
- :open_file_folder: title (Title or Description)
- :notebook: title (Title or Description): <span style="color: #006400">My company</span> ← loaded from the YAML file "config/03/config.yml"
- :notebook: color (Color): <span style="color: #B8860B">#d0b88b</span>
***
- [[tutorial v1.1_182] Auto save value](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_182/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_182~1..v1.1_182))