From 0c9ae4a01f0e465212561f8bc6cbb710d54f4c33 Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Tue, 2 Dec 2025 13:59:33 +0100 Subject: [PATCH] feat: document output --- README.fr.md | 22 +++++++ README.md | 22 ++++++- src/rougail/output_console/__init__.py | 79 ++++++++++++++++---------- src/rougail/output_console/config.py | 47 +++++++++------ 4 files changed, 121 insertions(+), 49 deletions(-) create mode 100644 README.fr.md diff --git a/README.fr.md b/README.fr.md new file mode 100644 index 0000000..91f6c49 --- /dev/null +++ b/README.fr.md @@ -0,0 +1,22 @@ +--- +gitea: none +include_toc: true +--- +[🇬🇧 (EN)](README.md) - [🇫🇷 (FR)](README.fr.md) + +## Configuration de rougail-console + +> **🛈 Informations** +> +> **Chemin** : console\ +> *`désactivé`*\ +> **Désactivé** : if console is not set in "[Sélection pour sortie](#step.output)" + +| Variable | Description | Valeur par défaut | Type | Validateur | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------| +| **console.show_secrets**
**Ligne de commande** :
• --console.show_secrets
• --console.no-show_secrets
**Variable d'environnement** : ROUGAILCLI_CONSOLE.SHOW_SECRETS | Voir les secrets plutôt que de les obscurcir. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | +| **console.mandatory**
**Ligne de commande** :
• --console.mandatory
• --console.no-mandatory
**Variable d'environnement** : ROUGAILCLI_CONSOLE.MANDATORY | Test les variables obligatoires avant de les afficher dans la console. | do not test if "cli.read_write" is true | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | +| **console.key_is_description**
**Ligne de commande** :
• --console.key_is_description
• --console.no-key_is_description
**Variable d'environnement** : ROUGAILCLI_CONSOLE.KEY_IS_DESCRIPTION | Dans l'arborescence la clé est la description de la famille ou de la variable au lieux de son nom
#
# undocumented_modes:
# description: Variables with those modes are not documented
# multi: true
# mandatory: false
# disabled:
# jinja: |
# {% if not modes_level %}
# there is no mode
# {% endif %}
# description: disabled when there is no mode available
# validators:
# - jinja: |
# {% if _.undocumented_modes not in modes_level %}
# this mode is not available
# {% endif %}
# description: verify if disable modes already exists. | true | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | +| **console.max_width**
**Ligne de commande** : --console.max_width
**Variable d'environnement** : ROUGAILCLI_CONSOLE.MAX_WIDTH | Maximum number of characters per line.
Null means unlimited. | | [`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) | The minimum value is 50. | + + diff --git a/README.md b/README.md index bd012ab..b7f7b07 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,22 @@ -# rougail-output-console +--- +gitea: none +include_toc: true +--- +[🇬🇧 (EN)](README.md) - [🇫🇷 (FR)](README.fr.md) + +## Configuration for rougail-console + +> **🛈 Informations** +> +> **Path**: console\ +> *`disabled`*\ +> **Disabled**: if console is not set in "[Select for output](#step.output)" + +| Variable | Description | Default value | Type | Validator | +|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------| +| **console.show_secrets**
**Command line**:
• --console.show_secrets
• --console.no-show_secrets
**Environment variable**: ROUGAILCLI_CONSOLE.SHOW_SECRETS | Show secrets instead of obscuring them. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | +| **console.mandatory**
**Command line**:
• --console.mandatory
• --console.no-mandatory
**Environment variable**: ROUGAILCLI_CONSOLE.MANDATORY | Test mandatories variables before display in console. | do not test if "cli.read_write" is true | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | +| **console.key_is_description**
**Command line**:
• --console.key_is_description
• --console.no-key_is_description
**Environment variable**: ROUGAILCLI_CONSOLE.KEY_IS_DESCRIPTION | In tree the key is the family or variable description inside of it's name
#
# undocumented_modes:
# description: Variables with those modes are not documented
# multi: true
# mandatory: false
# disabled:
# jinja: |
# {% if not modes_level %}
# there is no mode
# {% endif %}
# description: disabled when there is no mode available
# validators:
# - jinja: |
# {% if _.undocumented_modes not in modes_level %}
# this mode is not available
# {% endif %}
# description: verify if disable modes already exists. | true | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | +| **console.max_width**
**Command line**: --console.max_width
**Environment variable**: ROUGAILCLI_CONSOLE.MAX_WIDTH | Maximum number of characters per line.
Null means unlimited. | | [`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) | The minimum value is 50. | + diff --git a/src/rougail/output_console/__init__.py b/src/rougail/output_console/__init__.py index bf8ed06..e659a0a 100644 --- a/src/rougail/output_console/__init__.py +++ b/src/rougail/output_console/__init__.py @@ -38,7 +38,8 @@ class RougailOutputConsole: variable_undocumented_color = "bright_blue" variable_undocumented_and_modified_color = "red1" value_unmodified_color = "gold1" - value_default_color = "green" + value_modified_color = "green" + value_default_color = None def __init__( self, @@ -62,6 +63,7 @@ class RougailOutputConsole: self.config_owner_is_path = config_owner_is_path self.is_mandatory = self.rougailconfig["console.mandatory"] self.show_secrets = self.rougailconfig["console.show_secrets"] + self.max_width = self.rougailconfig["console.max_width"] self.key_is_description = self.rougailconfig["console.key_is_description"] try: self.undocumented_modes = set(self.rougailconfig["console.undocumented_modes"]) @@ -82,7 +84,7 @@ class RougailOutputConsole: if user_data_warnings is None: user_data_warnings = [] self.user_data_warnings = user_data_warnings - self.console = Console(force_terminal=True) + self.console = Console(force_terminal=True, width=self.max_width) self.out = [] self.root = self.get_root() @@ -113,7 +115,7 @@ class RougailOutputConsole: description = child.path(uncalculated=True) if child.isdynamic() and "{{ identifier }}" in description: description = description.replace( - "{{ identifier }}", child.identifiers()[-1] + "{{ identifier }}", str(child.identifiers()[-1]) ) if child.isoptiondescription(): @@ -162,7 +164,7 @@ class RougailOutputConsole: self.root, ) self.config.information.set("path_in_description", old_path_in_description) - if self.output.tree.children: + if self.output.tree and self.output.tree.children: self.header() self.end() return True @@ -232,9 +234,9 @@ class RougailOutputConsole: if self.value_unmodified_enable: header_value = f'[{self.value_unmodified_color}]{_("Default value")}[/{self.value_unmodified_color}]\n' if self.value_modified_enable: - header_value += _("Modified value") + "\n" + header_value += f'[{self.value_modified_color}]{_("Modified value")}[/{self.value_modified_color}]\n' if self.value_default_enable: - header_value += f'([{self.value_default_color}]:hourglass_flowing_sand: {_("Original default value")}[/{self.value_default_color}])\n' + header_value += f'(:hourglass_flowing_sand: {_("Original default value")})\n' caption = Table.grid(padding=1, collapse_padding=True) caption.pad_edge = False caption.add_row(caption_line[:-1], header_value[:-1]) @@ -330,34 +332,43 @@ class OutputFamily: is_leader: bool = False, no_icon: bool = False, ) -> None: - if parent is None: - tree = Tree - else: - tree = parent.add - if is_leader: - self.tree = tree( - ":notebook: " + _("{0}:").format(family), - guide_style="bold bright_blue", - ) - elif no_icon: - self.tree = tree( - f"{family}", - guide_style="bold bright_blue", - ) - else: - self.tree = tree( - f":open_file_folder: {family}", - guide_style="bold bright_blue", - ) + self.tree = None self.root = root + self.parent = parent + self.family = family + self.is_leader = is_leader + self.no_icon = no_icon self._yaml = _yaml self.key_is_description = key_is_description self.undocumented_modes = undocumented_modes + def get_tree(self): + if self.tree is None: + if self.parent is None: + tree = Tree + else: + tree = self.parent.add + if self.is_leader: + self.tree = tree( + ":notebook: " + _("{0}:").format(self.family), + guide_style="bold bright_blue", + ) + elif self.no_icon: + self.tree = tree( + self.family, + guide_style="bold bright_blue", + ) + else: + self.tree = tree( + f":open_file_folder: {self.family}", + guide_style="bold bright_blue", + ) + return self.tree + def add_family( self, option, - ) -> None: + ) -> 'OutputFamily': properties = option.property.get() if "hidden" in properties: self.root.variable_hidden_enable = True @@ -382,7 +393,7 @@ class OutputFamily: } ] ), - self.tree, + self.get_tree(), self.root, self._yaml, self.key_is_description, @@ -394,7 +405,6 @@ class OutputFamily: ): # value is undefined but not for leader variable properties = option.property.get() - color = None variable_color = None undocumented = self.undocumented_modes & properties hidden = False @@ -426,7 +436,7 @@ class OutputFamily: values.append( { "value": value, - "color": color, + "color": self.root.value_modified_color, "loaded_from": loaded_from, } ) @@ -494,6 +504,13 @@ class OutputFamily: else: self.root.value_default_enable = True color = self.root.value_default_color + follower_index = option.index() + if follower_index is not None: + loaded_from = option.information.get( + f"loaded_from_{follower_index}", None + ) + else: + loaded_from = option.information.get("loaded_from", None) values.append( { "value": None, @@ -519,14 +536,14 @@ class OutputFamily: option, ) if isinstance(value, list): - subtree = self.tree.add( + subtree = self.get_tree().add( ":notebook: " + _("{0}:").format(key), guide_style="bold bright_blue", ) for val in value: subtree.add(str(val)) else: - self.tree.add(":notebook: " + _("{0}: {1}").format(key, value)) + self.get_tree().add(":notebook: " + _("{0}: {1}").format(key, value)) def get_subconfig_with_default_value(self, suboption): default_owner = suboption.owner.default() diff --git a/src/rougail/output_console/config.py b/src/rougail/output_console/config.py index 25e13d1..d6c9bd1 100644 --- a/src/rougail/output_console/config.py +++ b/src/rougail/output_console/config.py @@ -29,10 +29,14 @@ def get_rougail_config( console: description: {_('Configuration for rougail-console')} disabled: - jinja: | + jinja: |- {{% if step.output is propertyerror or step.output != 'console' %}} - disabled + true + {{% else %}} + false {{% endif %}} + return_type: boolean + description: {_('if console is not set in "step.output"')} show_secrets: false # {_('Show secrets instead of obscuring them')} @@ -46,25 +50,34 @@ console: {{% else %}} true {{% endif %}} + description: {_('do not test if "cli.read_write" is true')} key_is_description: true # {_("In tree the key is the family or variable description inside of it's name")} +# +# undocumented_modes: +# description: {_('Variables with those modes are not documented')} +# multi: true +# mandatory: false +# disabled: +# jinja: | +# {{% if not modes_level %}} +# there is no mode +# {{% endif %}} +# description: {_('disabled when there is no mode available')} +# validators: +# - jinja: | +# {{% if _.undocumented_modes not in modes_level %}} +# this mode is not available +# {{% endif %}} +# description: {_('verify if disable modes already exists')} - undocumented_modes: - description: {_('Variables with those modes are not documented')} - multi: true + max_width: + description: {_("Maximum number of characters per line")} + help: {_('null means unlimited')} + type: integer mandatory: false - disabled: - jinja: | - {{% if not modes_level %}} - there is no mode - {{% endif %}} - description: {_('disabled when there is no mode available')} - validators: - - jinja: | - {{% if _.undocumented_modes not in modes_level %}} - this mode is not available - {{% endif %}} - description: {_('verify if disable modes already exists')} + params: + min_integer: 50 """ return { "name": "console",