From 40dadd6cba85dee14aa834a05f26c580294e2931 Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Sun, 7 Jun 2026 21:08:47 +0200 Subject: [PATCH] doc(improvement) --- docs/abstract.rst | 16 +++---- docs/index.rst | 1 + docs/structured_data.rst | 7 +++ docs/structured_data/data_integrity.rst | 12 +++++ docs/user_data/ansible.rst | 8 ++-- docs/user_data/bitwarden.rst | 8 ++-- docs/user_data/commandline.rst | 3 ++ docs/user_data/environment.rst | 8 ++-- docs/user_data/example.yaml | 53 ++++++++++++++++++++++ docs/user_data/prerequisites.rst | 59 +++++++++++++++++++++++++ docs/user_data/questionary.rst | 8 ++-- docs/user_data/yaml.rst | 17 ++++--- 12 files changed, 175 insertions(+), 25 deletions(-) create mode 100644 docs/user_data/example.yaml create mode 100644 docs/user_data/prerequisites.rst diff --git a/docs/abstract.rst b/docs/abstract.rst index 8052ce85c..5db0819bb 100644 --- a/docs/abstract.rst +++ b/docs/abstract.rst @@ -176,7 +176,7 @@ Here is a reminder of the different steps: - - Operator - Integrator -Variable lifetime +Variable lifecyle ---------------------- Rougail's a configuration language and data validation tool is designed @@ -184,14 +184,14 @@ to simplify defining, validating, and generating structured configuration and da Rougail aims at defining variables. -Here we are talking about the variable lifetime. +Here we are talking about the variable lifecyle. -The variable’s lifetime is the period between its creation and its destruction. +The variable’s lifecyle is the period between its creation and its destruction. The lifecycle of a variable includes the generic stages (like, in the C language): - Creation: variables are assigned a name and a type -- Initialization: they are assigned their first value +- Initialization: they are assigned their first value (we call it :term:`default value`) - Assignment: the variable's value is modified - Reading: the variable's value is used - Destruction: the variable terminates upon the destruction of the object @@ -207,7 +207,7 @@ But other concepts are included in the lifecycle: * - **Step** - Actor - - Lifetime + - Lifecyle * - **Structured data** - Integrator @@ -257,7 +257,7 @@ Variable definition settings are immutable. * - **Step** - Actor - - Lifetime + - Lifecyle - Mutability * - **Structured data** @@ -304,7 +304,7 @@ The configuration is said to be in :term:`read only mode`. * - **Step** - Actor - - Lifetime + - Lifecyle - Mutability - Value @@ -380,7 +380,7 @@ A picture is worth a thousand words: * - **Step** - Actor - - Lifetime + - Lifecyle - Mutability - Value - Access control diff --git a/docs/index.rst b/docs/index.rst index dae8faa3c..1ffcdb190 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -57,6 +57,7 @@ Rougail :titlesonly: :caption: User data + user_data/prerequisites user_data/index .. toctree:: diff --git a/docs/structured_data.rst b/docs/structured_data.rst index 48704f01e..809d33fb6 100644 --- a/docs/structured_data.rst +++ b/docs/structured_data.rst @@ -178,3 +178,10 @@ There is an execption. That what we call the short-hand declaration. Of course, it's not possible to fully customize the variable with this notation. Use shorthand notation whenever possible. This makes the file easier to read. + +Versioned +--------- + +The format can evolve. This means that parameters can be added, removed, or modified. +When writing structured data, you must always specify the format version. +You must also ensure that your Rougail version is compatible with your format version. diff --git a/docs/structured_data/data_integrity.rst b/docs/structured_data/data_integrity.rst index da87c04b3..41b0d457c 100644 --- a/docs/structured_data/data_integrity.rst +++ b/docs/structured_data/data_integrity.rst @@ -96,6 +96,18 @@ For certain types, there are a number of parameters that can be used to further .. _nullable_variable: +Custom type +''''''''''' + +It is not possible to create every possible type of variable. + +Therefore, it is necessary to provide a simple way to create these custom types. + +There are two ways to create a type: + +- creating a :term:`Tiramisu` type +- creating a type from an existing variable, see the tutorial with a real world sample :doc:`custom type <../tutorial/customtype>`. + Nullable variable ''''''''''''''''' diff --git a/docs/user_data/ansible.rst b/docs/user_data/ansible.rst index f6521b2f6..859cf5581 100644 --- a/docs/user_data/ansible.rst +++ b/docs/user_data/ansible.rst @@ -1,14 +1,16 @@ Load user data from Ansible compatible file =========================================== +Synopsis +------------- + .. note:: | Ansible offers a tool (ansible-vault) for encrypting inventory files. With this user data you can open an encrypt inventory file. This is a perfect way to manage a smooth migration from Ansible inventory to Rougail. Or it could be a way to encrypt these secrets in a file with a secure format. - | **Path**: ansible - | `*disabled*` | **Disabled**: if ansible is not set in "select for user data" (step.user_data). - +Parameters +-------------- .. list-table:: diff --git a/docs/user_data/bitwarden.rst b/docs/user_data/bitwarden.rst index 806df9e11..2ba3e296b 100644 --- a/docs/user_data/bitwarden.rst +++ b/docs/user_data/bitwarden.rst @@ -1,14 +1,16 @@ Load user data secrets from Bitwarden ===================================== +Synopsis +------------- + .. note:: | Load the secrets from Bitwarden (or a compatible server like Vaultwarden). The data is retrieved using the official command line "bw" or the alternative command "rbw" (faster). Before using Rougail, the command must be logged and unlocked. - | **Path**: bitwarden - | `*disabled*` | **Disabled**: if bitwarden is not set in "select for user data" (step.user_data). - +Parameters +-------------- .. list-table:: diff --git a/docs/user_data/commandline.rst b/docs/user_data/commandline.rst index ab166ef96..8df63d1f8 100644 --- a/docs/user_data/commandline.rst +++ b/docs/user_data/commandline.rst @@ -1,6 +1,9 @@ Load user data from commandline parser ======================================= +Synopsis +------------- + .. note:: | Load the user data from the current command line. diff --git a/docs/user_data/environment.rst b/docs/user_data/environment.rst index 43b31f321..94c5fe63b 100644 --- a/docs/user_data/environment.rst +++ b/docs/user_data/environment.rst @@ -1,6 +1,9 @@ Load user data from environment variables ========================================= +Synopsis +------------- + .. note:: | Variable values can be defined directly from an environment variable. @@ -10,11 +13,10 @@ Load user data from environment variables | Note that variable paths can contain dots ("."), which are not permitted everywhere. To avoid any issues, use the `env` command, for example: `env ROUGAIL_MY_FAMILY.MY_VARIABLE=1 rougail`. | | For values, there is no difference between a number and a letter (they can be enclosed in quotes or not). However, booleans are True or False. The separator for multiple variables is a comma. - | **Path**: environment - | `*disabled*` | **Disabled**: if environment is not set in "select for user data" (step.user_data). - +Parameters +-------------- .. list-table:: diff --git a/docs/user_data/example.yaml b/docs/user_data/example.yaml new file mode 100644 index 000000000..88e3ec0e6 --- /dev/null +++ b/docs/user_data/example.yaml @@ -0,0 +1,53 @@ +%YAML 1.2 +--- +version: 1.1 + +person: # Description of a person + + + firstname: # Last name of the person + + lastnames: [] # Last names of the person + + age: + description: Person's age + type: integer + params: + min_integer: 0 + max_integer: 120 + + legal_age: + description: The person is of legal age + type: boolean + default: + jinja: |- + {{ _.age is not none and _.age >= 18 }} + hidden: true + + drive_license: + description: The person has a driver's license + default: false + disabled: + variable: _.legal_age + when_not: true + + means_of_transport: + description: Means of transport used by the person + choices: + - human-powered + - public transport + - electric-assisted vehicle + - engine-powered without a license + - engine-powered + - others + validators: + - jinja: |- + {% if _.means_of_transport == "engine-powered" %} + {% if _.drive_license is propertyerror %} + {{ _.lastnames[0] }} {{ _.firstname }} is not of legal age but declares that he uses an engine-powered + {% elif not _.drive_license %} + {{ _.lastnames[0] }} {{ _.firstname }} does not have a license but declares that he uses an engine-powered + {% endif %} + {% endif %} + description: Engine-powered are only permitted for individuals with a driver's license +... diff --git a/docs/user_data/prerequisites.rst b/docs/user_data/prerequisites.rst new file mode 100644 index 000000000..8421eddfe --- /dev/null +++ b/docs/user_data/prerequisites.rst @@ -0,0 +1,59 @@ +Prerequisites +============= + +Installation +------------ + +We assume that Rougail's command line is :ref:`installed ` on your computer. + +Verify that you have correctly installed the tool by running: + +.. code-block:: bash + :class: terminal + + + $ rougail --cli.versions + tiramisu: x.x.x + tiramisu-cmdline-parser: x.x.x + rougail: x.x.x + rougail-cli: x.x.x + rougail-user-data-ansible: x.x.x + rougail-user-data-bitwarden: x.x.x + rougail-user-data-commandline: x.x.x + rougail-user-data-environment: x.x.x + rougail-user-data-questionary: x.x.x + rougail-user-data-yaml: x.x.x + rougail-output-ansible: x.x.x + rougail-output-display: x.x.x + rougail-output-doc: x.x.x + rougail-output-formatter: x.x.x + rougail-output-json: x.x.x + rougail-output-table: x.x.x + +Smoke test +---------- + +We need a Rougail structured data file to test and illustrate the different user data loading modules. + +.. literalinclude:: example.yaml + :caption: A example of structured data file place in the :file:`example.yaml` structure file + +Let's test this structured file: + +.. code-block:: bash + :class: terminal + + $ rougail -m example.yaml + +The output has to be: + +.. raw:: html + :class: terminal + + πŸ›‘ Caution + ┗━━ Description of a person + ┣━━ Last name of the person: πŸ›‘ mandatory variable but has no value + ┣━━ Last names of the person: πŸ›‘ mandatory variable but has no value + ┣━━ Person's age: πŸ›‘ mandatory variable but has no value + ┗━━ Means of transport used by the person: πŸ›‘ mandatory variable but has no value + diff --git a/docs/user_data/questionary.rst b/docs/user_data/questionary.rst index 0cbc4bfb6..fdeeed2f7 100644 --- a/docs/user_data/questionary.rst +++ b/docs/user_data/questionary.rst @@ -1,14 +1,16 @@ Define user data interactively in the console ============================================= +Synopsis +------------- + .. note:: | The user will enter variable values in a command-line interface. The variables will be displayed one after another, allowing the user to change or add values. - | **Path**: questionary - | `*disabled*` | **Disabled**: if questionary is not set in "select for user data" (step.user_data). - +Parameters +-------------- .. list-table:: diff --git a/docs/user_data/yaml.rst b/docs/user_data/yaml.rst index 86f2dac20..ff46954f5 100644 --- a/docs/user_data/yaml.rst +++ b/docs/user_data/yaml.rst @@ -1,14 +1,22 @@ -Charge user data from YAML file -=============================== +Load user data from YAML file +============================= + +Synopsis +------------- .. note:: - | **Path**: yaml - | `*disabled*` + | Variable values can be defined in a list of YAML files. | **Disabled**: if yaml is not set in "select for user data" (step.user_data). +Sample +------ + +Parameters +-------------- + .. list-table:: * - Variable @@ -61,4 +69,3 @@ Charge user data from YAML file - last - none -