rougail-tutorials/README.md

• Summary
• [tutorial v1.1_032] An hidden family (diff)

[tutorial v1.1_033)] A conditional hidden family with a variable

View the diff

Screenshot

Structure

firefox/00-proxy.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
...

firefox/10-manual.yml

%YAML 1.2
---
version: 1.1

manual:
  description: Manual proxy configuration
  disabled:
    variable: _.proxy_mode
    when_not: Manual proxy configuration

  http_proxy:  # HTTP Proxy

    address:
      description: HTTP address
      type: domainname
      params:
        allow_ip: true

    port:
      description: HTTP Port
      type: port
      default: 8080
...

firefox/20-manual.yml

%YAML 1.2
---
version: 1.1

manual:

  use_for_https: true  # Also use this proxy for HTTPS

  https_proxy:
    description: HTTPS Proxy
    hidden:
      variable: _.use_for_https

    address:
      description: HTTPS address
      type: domainname
      params:
        allow_ip: true

    port:
      description: HTTPS Port
      type: port
      default: 8080
...

Let's generate the documentation

foo@bar:~$ git switch --detach v1.1_033
foo@bar:~$ rougail -m firefox/ -o doc -do github

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

Manual proxy configuration

manual

disabled

Disabled: when the variable "proxy_mode" hasn't the value "Manual proxy configuration"

HTTP Proxy

manual.http_proxy

Variable	Description
manual.http_proxy.address domainname mandatory	HTTP address. Validator: the domain name can be an IP
manual.http_proxy.port port mandatory	HTTP Port. Validators: - well-known ports (1 to 1023) are allowed - registred ports (1024 to 49151) are allowed - private ports (greater than 49152) are allowed Default: 8080

Variable	Description
manual.use_for_https boolean mandatory	Also use this proxy for HTTPS. Default: true

HTTPS Proxy

manual.https_proxy

hidden

Hidden: when the variable "manual.use_for_https" has the value "true"

Variable	Description
manual.https_proxy.address domainname mandatory	HTTPS address. Validator: the domain name can be an IP
manual.https_proxy.port port mandatory	HTTPS Port. Validators: - well-known ports (1 to 1023) are allowed - registred ports (1024 to 49151) are allowed - private ports (greater than 49152) are allowed Default: 8080

Let's generate the changelog

foo@bar:~$ git switch --detach v1.1_033
foo@bar:~$ rougail -m firefox/ -o doc --doc.contents changelog -do github

New variables

Variable	Description
manual.https_proxy.address domainname mandatory	HTTPS address. Validator: the domain name can be an IP
manual.https_proxy.port port mandatory	HTTPS Port. Validators: - well-known ports (1 to 1023) are allowed - registred ports (1024 to 49151) are allowed - private ports (greater than 49152) are allowed Default: 8080

User datas

Example 1

config/01/config.yaml

---

Output

foo@bar:~$ git switch --detach v1.1_033
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/01/config.yaml

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

Example 2

config/02/config.yaml

---
proxy_mode: No proxy

Output

foo@bar:~$ git switch --detach v1.1_033
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/02/config.yaml

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

Example 3

config/03/config.yaml

---
proxy_mode: Manual proxy configuration

Output

foo@bar:~$ git switch --detach v1.1_033
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/03/config.yaml

🛑 ERRORS
┗━━ The following variables are mandatory but have no value:
    ┗━━ Manual proxy configuration
        ┗━━ HTTP Proxy
            ┗━━ HTTP address

Example 4

config/04/config.yaml

---
proxy_mode: foo

Output

foo@bar:~$ git switch --detach v1.1_033
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/04/config.yaml

🔔 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.yaml"
╭─────── Caption ────────╮
│ Variable Default value │
╰────────────────────────╯
Variables:
┗━━ 📓 Configure Proxy Access to the Internet: No proxy

Example 5

config/05/config.yaml

---
proxy_mode: 1

Output

foo@bar:~$ git switch --detach v1.1_033
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/05/config.yaml

🔔 WARNINGS
┗━━ the value "1" 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/05/config.yaml"
╭─────── Caption ────────╮
│ Variable Default value │
╰────────────────────────╯
Variables:
┗━━ 📓 Configure Proxy Access to the Internet: No proxy

• [tutorial v1.1_034] A calculated default value (diff)