• Summary
• [tutorial v1.1_000] Creating a structure file (diff)

[tutorial v1.1_001] Let’s add our first variable

Read the tutorial "Let’s add our first variable" in the documentation

Screenshot

Clone and install

To test this tutorial, you need to download this repository and install Rougail:

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:

git switch --detach v1.1_001

Structure

.
└── firefox
    └── 00-proxy.yml

Contents of the firefox/00-proxy.yml file

%YAML 1.2
---
version: 1.1

proxy_mode:
...

---

Let's generate the documentation```shell

rougail -m firefox/ -o doc

| Variable                                                                                                                                                   |
|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="proxy_mode" name="proxy_mode">proxy_mode</a>**<br/>[`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` |
***
### Let's generate the changelog```shell
rougail -m firefox/ -o doc --doc.contents changelog --doc.changelog.previous_json_file previous.yml

New variable

Variable
proxy_mode string mandatory

---

User datas### Example 1#### config/01/config.yml

---

---

Output```shell

rougail -m firefox/ -u yaml -yf config/01/config.yml

> [!CAUTION]
> 
> - proxy_mode: :stop_sign: <span style="color: #C23636">mandatory variable but has no value</span>

***
#### Output in read write mode```shell
rougail -m firefox/ -u yaml -yf config/01/config.yml --cli.read_write

Note

Caption:

• Variable
• Default value

Variables:

• 📓 proxy_mode: null

---

Example 2#### config/02/config.yml

---
proxy_mode: No proxy

---

Output```shell

rougail -m firefox/ -u yaml -yf config/02/config.yml

> [!NOTE]
>
> **Caption:**
> - Variable
> - <span style="color: #006400">Modified value</span>

Variables:
- :notebook: proxy_mode: <span style="color: #006400">No proxy</span> ← loaded from the YAML file "config/02/config.yml"

***
### Example 3#### config/03/config.yml
```yml
---
proxy_mode: 1

---

Output```shell

rougail -m firefox/ -u yaml -yf config/03/config.yml

> [!CAUTION]
> 
> - proxy_mode
>   - <span style='color: #EFBF04'>:bell: the value "1" is an invalid string, it's not a string, it will be ignored when loading from the YAML file "config/03/config.yml"</span>
>   - <span style='color: #C23636'>:stop_sign: mandatory variable but has no value</span>

***
#### Output when invalid user data is an error```shell
rougail -m firefox/ -u yaml -yf config/03/config.yml --cli.invalid_user_data_error

Caution

• proxy_mode
  • 🛑 the value "1" is an invalid string, it's not a string, it has been loading from the YAML file "config/03/config.yml"
  • 🛑 mandatory variable but has no value

---

• [tutorial v1.1_002] Describe the variable (diff)