stove/rougail-tutorials

Fork 0

Emmanuel Garette 444ef68684 [tutorial v1.1_063)] Examples (config and doc)

2025-11-04 19:22:31 +01:00

34 KiB

Raw Blame History

[tutorial v1.1_063)] Examples

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

  '{{ identifier }}_proxy':
    description: '{{ identifier }} Proxy'
    hidden:
      jinja: |-
        {% if my_identifier == 'HTTPS' and manual.use_for_https %}
          HTTPS is same has HTTP
        {% endif %}        
      description: in HTTPS case if "manual.use_for_https" is set to True
      params:
        my_identifier:
          type: identifier
    dynamic:
      - HTTPS
      - SOCKS

    address:
      description: '{{ identifier }} address'
      default:
        variable: __.http_proxy.address

    port:
      description: '{{ identifier }} port'
      default:
        variable: __.http_proxy.port

    version:
      description: SOCKS host version used by proxy
      choices:
        - v4
        - v5
      default: v5
      disabled:
        type: identifier
        when: HTTPS
...

firefox/30-auto.yml

%YAML 1.2
---
version: 1.1

auto:
  description: Automatic proxy configuration URL
  type: web_address
  disabled:
    variable: _.proxy_mode
    when_not: Automatic proxy configuration URL
...

firefox/40-no_proxy.yml

%YAML 1.2
---
version: 1.1

no_proxy:
  description: Address for which proxy will be desactivated
  examples:
    - .mozilla.org
    - .net.nz
    - 192.168.1.0/24
  type: domainname
  params:
    allow_ip: true
    allow_cidr_network: true
    allow_without_dot: true
    allow_startswith_dot: true
  multi: true
  mandatory: false
  disabled:
    variable: _.proxy_mode
    when: No proxy
...

Let's generate the documentation

foo@bar:~$ git switch --detach v1.1_063
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 or SOCKS Proxy

This family builds families dynamically

manual.https_proxy
manual.socks_proxy

hidden

Hidden: in HTTPS case if "manual.use_for_https" is set to True

Identifiers:
- HTTPS
- SOCKS

Variable	Description
manual.https_proxy.address manual.socks_proxy.address `domainname` `mandatory`	HTTPS or SOCKS address. Validator: the domain name can be an IP Default: the value of the variable "manual.http_proxy.address"
manual.https_proxy.port manual.socks_proxy.port `port` `mandatory`	HTTPS or SOCKS 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: the value of the variable "manual.http_proxy.port"
manual.https_proxy.version manual.socks_proxy.version `choice` `mandatory` `disabled`	SOCKS host version used by proxy. Choices: - v4 - v5 ← (default) Disabled: when the identifier is "HTTPS"

Variable	Description
auto `web_address` `mandatory` `disabled`	Automatic proxy configuration URL. Validator: the domain name in web address can be only a hostname Disabled: when the variable "proxy_mode" hasn't the value "Automatic proxy configuration URL"
no_proxy `domainname` `disabled` `unique` `multiple`	Address for which proxy will be desactivated. Validators: - the domain name can starts by a dot - the domain name can be a hostname - the domain name can be an IP - the domain name can be network in CIDR format Examples: - .mozilla.org - .net.nz - 192.168.1.0/24 Disabled: when the variable "proxy_mode" has the value "No proxy"

Let's generate the changelog

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

Modified variable

Variable	Description
no_proxy `domainname` `disabled` `unique` `multiple`	Address for which proxy will be desactivated. Validators: - the domain name can starts by a dot - the domain name can be a hostname - the domain name can be an IP - the domain name can be network in CIDR format Examples: - .mozilla.org - .net.nz - 192.168.1.0/24 Disabled: when the variable "proxy_mode" has the value "No proxy"

User datas

Example 1

config/01/config.yaml

---

Output

foo@bar:~$ git switch --detach v1.1_063
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_063
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_063
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
        ┗━━ SOCKS Proxy
            ┗━━ SOCKS address

Example 4

config/04/config.yaml

---
proxy_mode: foo

Output

foo@bar:~$ git switch --detach v1.1_063
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_063
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_064] Help (diff)

34 KiB Raw Blame History

[tutorial v1.1_063)] Examples

Screenshot

Structure

firefox/00-proxy.yml

firefox/10-manual.yml

firefox/20-manual.yml

firefox/30-auto.yml

firefox/40-no_proxy.yml

Let's generate the documentation

Manual proxy configuration

HTTP Proxy

HTTPS Proxy or SOCKS Proxy

Let's generate the changelog

Modified variable

User datas

Example 1

config/01/config.yaml

Output

Example 2

config/02/config.yaml

Output

Example 3

config/03/config.yaml

Output

Example 4

config/04/config.yaml

Output

Example 5

config/05/config.yaml

Output

34 KiB

Raw Blame History