rougail-tutorials/README.md

• Summary
• [tutorial v1.1_003] Set a default value (diff)

[tutorial v1.1_010] A variable with a list of possible values

View the diff

Read 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_010

Structure

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

Contents of the firefox/00-proxy.yml file

%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
...

Let's generate the documentation

rougail -m firefox/ -o doc

Variable	Description
proxy_mode choice mandatory	Configure Proxy Access to the Internet. Choices: • No proxy ← (default) • Auto-detect proxy settings for this network • Use system proxy settings • Manual proxy configuration • Automatic proxy configuration URL

Let's generate the changelog

rougail -m firefox/ -o doc --doc.contents changelog

Modified variable

Variable	Description
proxy_mode choice mandatory	Configure Proxy Access to the Internet. Choices: • No proxy ← (default) • Auto-detect proxy settings for this network • Use system proxy settings • Manual proxy configuration • Automatic proxy configuration URL

User datas

Example 1

config/01/config.yml

---

Output

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

╭──────────────────── Caption ─────────────────────╮
│ Undocumented but modified variable Default value │
╰──────────────────────────────────────────────────╯
Variables:
┗━━ 📓 Configure Proxy Access to the Internet: No proxy

Example 2

config/02/config.yml

---
proxy_mode: No proxy

Output

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

╭─────────────────────────── Caption ────────────────────────────╮
│ Undocumented but modified variable Modified value              │
│                                    (⏳ Original default value) │
╰────────────────────────────────────────────────────────────────╯
Variables:
┗━━ 📓 Configure Proxy Access to the Internet: No proxy ◀ loaded from the YAML 
    file "config/02/config.yml" (⏳ No proxy)

Example 3

config/03/config.yml

---
proxy_mode: Manual proxy configuration

Output

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

╭─────────────────────────── Caption ────────────────────────────╮
│ Undocumented but modified variable Modified value              │
│                                    (⏳ Original default value) │
╰────────────────────────────────────────────────────────────────╯
Variables:
┗━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ 
    loaded from the YAML file "config/03/config.yml" (⏳ No proxy)

Example 4

config/04/config.yml

---
proxy_mode: foo

Output

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

🔔 WARNINGS
┗━━ 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 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 ─────────────────────╮
│ Undocumented but modified variable Default value │
╰──────────────────────────────────────────────────╯
Variables:
┗━━ 📓 Configure Proxy Access to the Internet: No proxy

Output when invalid user datas is an error

rougail -m firefox/ -u yaml -yf config/04/config.yml --cli.invalid_user_datas_error

🛑 ERRORS
┗━━ 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 configuration", "No 
    proxy" and "Use system proxy settings" are allowed, it will be ignored when 
    loading from the YAML file "config/04/config.yml"

• [tutorial v1.1_020] Creating a new family (diff)