From a44087e3b30bc3c65b9e68158d72976208a77ca7 Mon Sep 17 00:00:00 2001 From: gwen Date: Fri, 22 May 2026 17:46:28 +0200 Subject: [PATCH] docs(v1.1_121): help string --- docs/cli.rst | 20 +++++++ docs/tutorial/examples.rst | 120 +++++++++++++++++++++++++++++++++++-- 2 files changed, 136 insertions(+), 4 deletions(-) diff --git a/docs/cli.rst b/docs/cli.rst index c905cc9d6..601fe8cf4 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -142,6 +142,26 @@ Le output doc :: rougail -m structure.yml -o doc --doc.output_format github > README.md +:: + + doc: + Generate documentation from structural files + + -do [{console,asciidoc,html,github,gitlab,json}], --doc.output_format [{console,asciidoc,html,github,gitlab,json}] + The output format of the generated documentation (default: console) + -dm [{two_columns,three_columns,four_columns,five_columns,six_columns}], --doc.tabular_template [{two_columns,three_columns,four_columns,five_columns,six_columns}] + Generate document with this tabular model (default: two_columns) + -dc {variables,example,changelog} [{variables,example,changelog} ...], --doc.contents {variables,example,changelog} [{variables,example,changelog} ...] + Generated content (default: variables) + -dt [TITLE_LEVEL], --doc.title_level [TITLE_LEVEL] + Starting title level (default: 1) + --doc.default_values Modify values to document all variables (default: True) + --doc.no-default_values + --doc.document_a_type + Documentation a structural type (default: False) + --doc.no-document_a_type + + Le formatter diff --git a/docs/tutorial/examples.rst b/docs/tutorial/examples.rst index bfc5b5eb9..5b919d3e4 100644 --- a/docs/tutorial/examples.rst +++ b/docs/tutorial/examples.rst @@ -70,6 +70,8 @@ Let's give some usage examples of how to use our `no_proxy` variable: Here we can see that there are no default values set and as our variable is not :term:`mandatory`, if we don't set values in the user data files as the `no_proxy` variable is :term:`multi`, the `no_proxy` value will be the empty list `[]`: +If we launch the Rougail CLI on user data: + .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/config.yml :language: yaml :caption: The :file:`config/03/config.yml` user data file with an `example` parameter but no value set @@ -78,10 +80,8 @@ if we don't set values in the user data files as the `no_proxy` variable is :ter --- proxy_mode: Automatic proxy configuration URL auto: https://auto.proxy.net/wpad.dat - no_proxy: - - example.net - - 192.168.1.0/24 +we can see that the `no_proxy` variable has no user data settings. .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/cmd_ro.txt @@ -90,6 +90,8 @@ if we don't set values in the user data files as the `no_proxy` variable is :ter .. rougail -m firefox/ --types types/proxy -u yaml -yf config/01/config.yml +we do indeed obtain the value empty list `[]` for the `no_proxy` variable: + .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/output_ro.html :class: output @@ -108,10 +110,14 @@ if we don't set values in the user data files as the `no_proxy` variable is :ter .. type-along:: If we set some user data values +Just to be thorough, let's look at what happens in a case where there is a value for `no_proxy` entered in the user data file: + .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/config.yml :language: yaml :caption: The :file:`config/03/config.yml` user data file with some value set +We launch the Rougail ClI + .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/cmd_ro.txt :class: terminal @@ -119,6 +125,8 @@ if we don't set values in the user data files as the `no_proxy` variable is :ter .. rougail -m firefox/ --types types/proxy -u yaml -yf config/02/config.yml +And we have the `no_proxy`'s expected value. No trace in the output of the examples settings of the variable: + .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/output_ro.html :class: output @@ -137,5 +145,109 @@ if we don't set values in the user data files as the `no_proxy` variable is :ter ┣━━ example.net ◀ loaded from the YAML file "config/02/config.yml" ┗━━ 192.168.1.0/24 ◀ loaded from the YAML file "config/02/config.yml" -.. note:: In all cases, we can see that none of the values ​​cited in the examples (`.mozilla.org`, `.net.nz`) appear. +In all cases, we can see that none of the values ​​cited in the examples (`.mozilla.org`, `.net.nz`) appear. + + +.. type-along:: In that case, is there a use for these examples? + +This examples parameter is useful when generating variable documentation. That's where the examples appear. + +If we launch the Rougail CLI for the documentation generation: + +.. code-block:: bash + + rougail -m firefox --types types/proxy -o doc --doc.output_format html + +We have this output: + +.. raw:: html + :class: output + + + + + + + + + +
Variable Description
auto
web address 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 "proxy_mode" hasn't the value "Automatic proxy configuration URL"
no_proxy
domainname multiple disabled unique		Address for which proxy will be desactivated.
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 "proxy_mode" has the value "No proxy"
+ +.. + ├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────┤ + │ no_proxy │ Address for which proxy will be desactivated. │ + │ domainname multiple disabled unique │ 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 "proxy_mode" has the value "No proxy" │ + └─────────────────────────────────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────┘ + +we can see that this time the examples (`.mozilla.org`, `.net.nz`) appear. + +Help +------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the :tutorial:`v1.1_121 ` version:: + + git switch --detach v1.1_121 + +Could we define personalized assistance, in the same way that we defined examples? + +Yes, very simply: we add a `help` parameter to our `no_proxy` variable: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_121/firefox/40-no_proxy.yml + :language: yaml + :caption: The :file:`firefox/40-no_proxy` structure definition file with an `example` parameter + + +In the same way, this help `"Connections to localhost, 127.0.0.1/8 and ::1 are never proxied"` will appear in the documentation: + +.. raw:: html + :class: output + + + + + + + + + +
Variable Description
auto
web address 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 "proxy_mode" hasn't the value "Automatic proxy configuration URL"
no_proxy
domainname multiple 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 "proxy_mode" has the value "No proxy"
+ + + + + +.. keypoints:: Key points + + - We have seen how to give examples, simply with the `examples` parameter + - We have seen how to specify a help, simply with the `help` parameter