rougail-tutorials/README.md

• Summary
• [tutorial v1.1_142] A web_address variable (diff)

[tutorial v1.1_150] A variable with custom validation

Read the tutorial "A variable with custom validation" 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_150

Structure

.
├── firefox
│   ├── 00-proxy.yml
│   ├── 10-manual.yml
│   ├── 20-manual.yml
│   ├── 30-auto.yml
│   ├── 40-no_proxy.yml
│   ├── 50-prompt_authentication.yml
│   ├── 55-proxy_dns_socks5.yml
│   └── 60-dns_over_https.yml
└── types
    └── proxy
        └── 00-type.yml

Contents of the firefox/60-dns_over_https.yml file

%YAML 1.2
---
version: 1.1

dns_over_https:  # DNS over HTTPS

  enable_dns_over_https: false  # Enable DNS over HTTPS

  provider:
    description: Use Provider
    choices:
      - Cloudflare
      - NextDNS
      - Custom
    default: Cloudflare
    disabled:
      variable: _.enable_dns_over_https
      when: false

  custom_dns_url:
    description: Custom DNS URL
    type: web_address
    validators:
      - jinja: |-
          {{ _.custom_dns_url.startswith("http://") }}          
        return_type: boolean
        description: must starts with 'https://' only
    disabled:
      jinja: |-
        {{ _.provider is propertyerror or _.provider != 'Custom' }}        
      return_type: boolean
      description: if "_.provider" is not "Custom"
...

---

Let's generate the documentation

rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -o doc

View the documentation file

---

Let's generate the changelog

rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -o doc --doc.contents changelog --doc.changelog.previous_json_file previous.yml

View the changelog file

---

User datas

Example 1

config/01/config.yml

---

---

Output

rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/01/config.yml

Note

Caption:

• Variable
• Default value

Variables:

• 📓 proxy_mode (Configure Proxy Access to the Internet): No proxy
• 📂 dns_over_https (DNS over HTTPS)
  • 📓 enable_dns_over_https (Enable DNS over HTTPS): false

---

Example 2

config/02/config.yml

---
dns_over_https:
  enable_dns_over_https: true

---

Output

rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/02/config.yml

Note

Caption:

• Variable
• Default value
• Modified value
• (⏳ Original default value)

Variables:

• 📓 proxy_mode (Configure Proxy Access to the Internet): No proxy
• 📂 dns_over_https (DNS over HTTPS)
  • 📓 enable_dns_over_https (Enable DNS over HTTPS): true ← loaded from the YAML file "config/02/config.yml" (⏳ false)
  • 📓 provider (Use Provider): Cloudflare

---

Example 3

config/03/config.yml

---
dns_over_https:
  enable_dns_over_https: true
  provider: Custom
  custom_dns_url: http://dns.net

---

Output

rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/03/config.yml

Caution

• dns_over_https (DNS over HTTPS)
  • custom_dns_url (Custom DNS URL)
    • 🔔 the value "http://dns.net" is an invalid URL, must starts with 'https://' only, it will be ignored when loading from the YAML file "config/03/config.yml"
    • 🛑 mandatory variable but has no value

---

Example 4

config/04/config.yml

---
dns_over_https:
  enable_dns_over_https: true
  provider: Custom
  custom_dns_url: https://dns.net

---

Output

rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/04/config.yml

Note

Caption:

• Variable
• Default value
• Modified value
• (⏳ Original default value)

Variables:

• 📓 proxy_mode (Configure Proxy Access to the Internet): No proxy
• 📂 dns_over_https (DNS over HTTPS)
  • 📓 enable_dns_over_https (Enable DNS over HTTPS): true ← loaded from the YAML file "config/04/config.yml" (⏳ false)
  • 📓 provider (Use Provider): Custom ← loaded from the YAML file "config/04/config.yml" (⏳ Cloudflare)
  • 📓 custom_dns_url (Custom DNS URL): https://dns.net ← loaded from the YAML file "config/04/config.yml"

---

• [tutorial v1.1_160] Namespace (diff)