stove/rougail-tutorials
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
rougail-tutorials/README.md

27 KiB
Raw Blame History

[tutorial v1.1_181] Calculate a random color

Read the tutorial "Calculate a random color" in the documentation

Screenshot

Firefox Proxy setting

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_181

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
├── foxyproxy
│   └── 00-foxyproxy.yml
└── types
    └── proxy
        └── 00_type.yml


Contents of the foxyproxy/00-foxyproxy.yml file

%YAML 1.2
---
version: 1.1

proxies:
  description: Proxy configuration
  type: leadership

  title:
    description: Title or Description
    mandatory: false

  color:
    description: Color
    regexp: ^#(?:[0-9a-f]{3}){1,2}$
    default:
      jinja: >-
        #{%- for i in range(6) -%}{{- '0123456789abcdef' | random -}}{%- endfor -%}        
      description: random color value
...

Let's generate the documentation

rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -o doc

Firefox

Note

This family is a namespace.
Path: firefox
basic

Variable Description
firefox.proxy_mode
choice standard 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

Note

Path: firefox.manual
basic disabled
Disabled: when the variable "Configure Proxy Access to the Internet" hasn't the value "Manual proxy configuration"

HTTP Proxy

Note

Path: firefox.manual.http_proxy
basic

Variable Description
firefox.manual.http_proxy.address
domainname basic mandatory		 Proxy address.
Validators:
• type domainname
• the domain name can be an IP
firefox.manual.http_proxy.port
port standard mandatory		 Proxy 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
firefox.manual.use_for_https
boolean standard mandatory		 Also use this proxy for HTTPS.
Default: true
HTTPS Proxy

Note

Path: firefox.manual.https_proxy
standard hidden
Hidden: when the variable "Also use this proxy for HTTPS" has the value "true"

Variable Description
firefox.manual.https_proxy.address
domainname standard mandatory		 Proxy address.
Validators:
• type domainname
• the domain name can be an IP
Default: the value of the variable "Proxy address"
firefox.manual.https_proxy.port
port standard mandatory		 Proxy 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 "Proxy port"
SOCKS Proxy

Note

Path: firefox.manual.socks_proxy
standard

Variable Description
firefox.manual.socks_proxy.address
domainname standard mandatory		 Proxy address.
Validators:
• type domainname
• the domain name can be an IP
Default: the value of the variable "Proxy address"
firefox.manual.socks_proxy.port
port standard mandatory		 Proxy 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 "Proxy port"
firefox.manual.socks_proxy.version
choice standard mandatory		 SOCKS host version used by proxy.
Choices:
• v4
• v5 ← (default)
Variable Description
firefox.auto
web address basic mandatory disabled		 Automatic proxy configuration URL.
Validators:
• well-known ports (1 to 1023) are allowed
• registred ports (1024 to 49151) are allowed
• type domainname
• the domain name can be a hostname
Disabled: when the variable "Configure Proxy Access to the Internet" hasn't the value "Automatic proxy configuration URL"
firefox.no_proxy
domainname multiple standard disabled unique		 Address for which proxy will be desactivated.
Connections to localhost, 127.0.0.1/8 and ::1 are never proxied.
Validators:
• type domainname
• 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 "Configure Proxy Access to the Internet" has the value "No proxy"
firefox.prompt_authentication
boolean standard mandatory disabled		 Prompt for authentication if password is saved.
Default: true
Disabled: when the variable "Configure Proxy Access to the Internet" has the value "No proxy"
firefox.proxy_dns_socks5
boolean advanced mandatory disabled		 Use proxy DNS when using SOCKS v5.
Default: false
Disabled: if "Configure Proxy Access to the Internet" is not "Manual proxy configuration"
or "SOCKS host version used by proxy" is "v4"
DNS over HTTPS

Note

Path: firefox.dns_over_https
basic

Variable Description
firefox.dns_over_https.enable_dns_over_https
boolean standard mandatory		 Enable DNS over HTTPS.
Default: false
firefox.dns_over_https.provider
choice standard mandatory disabled		 Use Provider.
Choices:
• Cloudflare ← (default)
• NextDNS
• Custom
Disabled: when the variable "Enable DNS over HTTPS" has the value "false"
firefox.dns_over_https.custom_dns_url
web address basic mandatory disabled		 Custom DNS URL.
Validators:
• well-known ports (1 to 1023) are allowed
• registred ports (1024 to 49151) are allowed
• type domainname
• the domain name can be a hostname
• must starts with 'https://' only
Disabled: if "Use Provider" is not "Custom"

FoxyProxy

Note

This family is a namespace.
Path: foxyproxy
standard

Proxy configuration

Note

This family contains lists of variable blocks.
Path: foxyproxy.proxies
standard

Variable Description
foxyproxy.proxies.title
string multiple standard unique		 Title or Description.
foxyproxy.proxies.color
regexp standard mandatory		 Color.
Validator: text based with regular expressions "^#(?:[0-9a-f]{3}){1,2}$"
Default: random color value

Let's generate the changelog

rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -o doc --doc.contents changelog --doc.changelog.previous_json_file previous.yml

Modified variable

Variable Description
foxyproxy.proxies.color
basic standard regexp standard mandatory		 Color.
Validator: text based with regular expressions "^#(?:[0-9a-f]{3}){1,2}$"
Default: random color value

User datas

Example 1

config/01/config.yml

---

Output

rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/01/config.yml

Note

Caption:

  • Variable
  • Default value

Variables:

  • 📂 firefox (Firefox)
    • 📓 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
  • 📂 foxyproxy (FoxyProxy)
    • 📂 proxies (Proxy configuration): []

Example 2

config/02/config.yml

---
foxyproxy:
  proxies:
    - title: My company

Output

rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/02/config.yml

Note

Caption:

  • Variable
  • Default value
  • Modified value

Variables:

  • 📂 firefox (Firefox)
    • 📓 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
  • 📂 foxyproxy (FoxyProxy)
    • 📂 proxies (Proxy configuration)
      • 📂 title (Title or Description)
        • 📓 title (Title or Description): My company ← loaded from the YAML file "config/02/config.yml"
        • 📓 color (Color): #00f139

Example 3

config/03/config.yml

---
foxyproxy:
  proxies:
    - title: My company

Output

rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/03/config.yml

Note

Caption:

  • Variable
  • Default value
  • Modified value

Variables:

  • 📂 firefox (Firefox)
    • 📓 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
  • 📂 foxyproxy (FoxyProxy)
    • 📂 proxies (Proxy configuration)
      • 📂 title (Title or Description)
        • 📓 title (Title or Description): My company ← loaded from the YAML file "config/03/config.yml"
        • 📓 color (Color): #d0b88b