stove/rougail-output-doc
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity

feat: remove doc.root, pass directly the family to doc output (be careful, add true_config parameter too)

Browse source
This commit is contained in:
egarette@silique.fr 2026-01-04 19:16:18 +01:00
parent e3ad3be95d
commit d229eb2a34
38 changed files with 479 additions and 510 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
README.fr.md
View file

@ -15,13 +15,12 @@ include_toc: true
| Variable | Description | Valeur par défaut | Type | Contrôle des accès | Validateur |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|-------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="doc.output_format" name="doc.output_format">doc.output_format</a>**<br/>**Ligne de commande** : -do, --doc.output_format<br/>**Variable d'environnement** : DOC.OUTPUT_FORMAT | Le format de sortie de la documentation générée. | console | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | **Choix** : <br/>•&nbsp;console<br/>•&nbsp;asciidoc<br/>•&nbsp;html<br/>•&nbsp;github<br/>•&nbsp;gitlab<br/>•&nbsp;json |
| **<a id="doc.tabular_template" name="doc.tabular_template">doc.tabular_template</a>**<br/>**Ligne de commande** : -dm, --doc.tabular_template<br/>**Variable d'environnement** : DOC.TABULAR_TEMPLATE | Génère la documentation avec ce modèle de tableau.<br/>Les variables sont documentées avec une vue tableau. Une sélection de modèle vous permet de choisir le contenu de chaque colonne. | two_columns | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | *`désactivé`*<br/>**Désactivé** : "[Le format de sortie de la documentation générée](#doc.output_format)" en json n\'est pas compatible avec cette variable<br/> | **Choix** : <br/>•&nbsp;two_columns<br/>•&nbsp;three_columns<br/>•&nbsp;four_columns<br/>•&nbsp;five_columns<br/>•&nbsp;six_columns |
| **<a id="doc.contents" name="doc.contents">doc.contents</a>**<br/>**Ligne de commande** : -dc, --doc.contents<br/>**Variable d'environnement** : DOC.CONTENTS | Contenu généré.<br/>Vous pouvez générer trois type de documentation. Toutes les variables (&quot;variables&quot;), un exemple de fichier au format YAML (&quot;example&quot;) ou le journal des changements (&quot;changelog&quot;). | •&nbsp;variables | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` `obligatoire` | *`cachée`*<br/>**Cachée** : "[Le format de sortie de la documentation générée](#doc.output_format)" en json n'est pas compatible avec "[Contenu généré](#doc.contents)" changelog or example<br/> | `unique`<br/>**Choix** : <br/>•&nbsp;variables<br/>•&nbsp;example<br/>•&nbsp;changelog |
| **<a id="doc.title_level" name="doc.title_level">doc.title_level</a>**<br/>**Ligne de commande** : -dt, --doc.title_level<br/>**Variable d'environnement** : DOC.TITLE_LEVEL | Niveau de titre de départ. | 1 | [`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | |
| **<a id="doc.output_format" name="doc.output_format">doc.output_format</a>**<br/>**Ligne de commande** : <br/>-do, --doc.output_format<br/>**Variable d'environnement** : DOC.OUTPUT_FORMAT | Le format de sortie de la documentation générée. | console | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | **Choix** : <br/>•&nbsp;console<br/>•&nbsp;asciidoc<br/>•&nbsp;html<br/>•&nbsp;github<br/>•&nbsp;gitlab<br/>•&nbsp;json |
| **<a id="doc.tabular_template" name="doc.tabular_template">doc.tabular_template</a>**<br/>**Ligne de commande** : <br/>-dm, --doc.tabular_template<br/>**Variable d'environnement** : DOC.TABULAR_TEMPLATE | Génère la documentation avec ce modèle de tableau.<br/>Les variables sont documentées avec une vue tableau. Une sélection de modèle vous permet de choisir le contenu de chaque colonne. | two_columns | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | *`désactivé`*<br/>**Désactivé** : "[Le format de sortie de la documentation générée](#doc.output_format)" en json n\'est pas compatible avec cette variable<br/> | **Choix** : <br/>•&nbsp;two_columns<br/>•&nbsp;three_columns<br/>•&nbsp;four_columns<br/>•&nbsp;five_columns<br/>•&nbsp;six_columns |
| **<a id="doc.contents" name="doc.contents">doc.contents</a>**<br/>**Ligne de commande** : <br/>-dc, --doc.contents<br/>**Variable d'environnement** : DOC.CONTENTS | Contenu généré.<br/>Vous pouvez générer trois type de documentation. Toutes les variables (&quot;variables&quot;), un exemple de fichier au format YAML (&quot;example&quot;) ou le journal des changements (&quot;changelog&quot;). | •&nbsp;variables | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` `obligatoire` | *`cachée`*<br/>**Cachée** : "[Le format de sortie de la documentation générée](#doc.output_format)" en json n'est pas compatible avec "[Contenu généré](#doc.contents)" changelog or example<br/> | `unique`<br/>**Choix** : <br/>•&nbsp;variables<br/>•&nbsp;example<br/>•&nbsp;changelog |
| **<a id="doc.title_level" name="doc.title_level">doc.title_level</a>**<br/>**Ligne de commande** : <br/>-dt, --doc.title_level<br/>**Variable d'environnement** : DOC.TITLE_LEVEL | Niveau de titre de départ. | 1 | [`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | |
| **<a id="doc.default_values" name="doc.default_values">doc.default_values</a>**<br/>**Ligne de commande** : <br/>•&nbsp;--doc.default_values<br/>•&nbsp;--doc.no-default_values<br/>**Variable d'environnement** : DOC.DEFAULT_VALUES | Modifier les valeurs pour documenter toutes les variables.<br/>Pour documenter les variables des leadership ou des familles dynamiques, il est parfois nécessaire de générer des valeurs, qui peuvent modifier les valeurs de la configuration. Soyez vigilent si vous réutilisez cette configuration. | true | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | |
| **<a id="doc.true_color" name="doc.true_color">doc.true_color</a>**<br/>**Ligne de commande** : <br/>•&nbsp;--doc.true_color<br/>•&nbsp;--doc.no-true_color<br/>**Variable d'environnement** : DOC.TRUE_COLOR | Afficher la documentation dans la console en permanence avec un terminal en couleurs réelles. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | *`désactivé`*<br/>**Désactivé** : lorsque la variable "[Le format de sortie de la documentation générée](#doc.output_format)" n'a pas la valeur "console" | |
| **<a id="doc.root" name="doc.root">doc.root</a>**<br/>**Ligne de commande** : -dr, --doc.root<br/>**Variable d'environnement** : DOC.ROOT | Documenter les variables enfants de cette famille.<br/>Par défaut, toute les variables accessibles sont incluent dans la documentation. Il est possible de définir une famille a partir de laquelle la documentation doit être générée. | | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) | | |
### Les variables pour cette famille sont documentés dans un autre fichier
@ -29,14 +28,12 @@ include_toc: true
>
> Si vous séparez les variables dans différents fichiers, le lien entre les variables va être cassé. Dans ce cas, vous devez définit différents nom de fichiers pour les fichiers contenant ces variables.\
> Cette famille contient des listes de bloc de variable.\
> **Chemin** : doc.other_root_filenames\
> *`désactivé`*\
> **Désactivé** : lorsque la variable "[Documenter les variables enfants de cette famille](#doc.root)" a la valeur "null"
> **Chemin** : doc.other_root_filenames
| Variable | Description | Type | Validateur |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| **<a id="doc.other_root_filenames.root_path" name="doc.other_root_filenames.root_path">doc.other_root_filenames.root_path</a>**<br/>**Ligne de commande** : --doc.other_root_filenames.root_path<br/>**Variable d'environnement** : DOC.OTHER_ROOT_FILENAMES.ROOT_PATH | Ce fichier contient les variables enfants de la famille. | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` | `unique` |
| **<a id="doc.other_root_filenames.filename" name="doc.other_root_filenames.filename">doc.other_root_filenames.filename</a>**<br/>**Ligne de commande** : --doc.other_root_filenames.filename<br/>**Variable d'environnement** : DOC.OTHER_ROOT_FILENAMES.FILENAME | Nom du fichier. | [`UNIX filename`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | •&nbsp;le nom de fichier peut être une chemin relatif<br/>•&nbsp;type de fichier autorisé: "file". |
| Variable | Description | Type | Validateur |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| **<a id="doc.other_root_filenames.root_path" name="doc.other_root_filenames.root_path">doc.other_root_filenames.root_path</a>**<br/>**Ligne de commande** : <br/>--doc.other_root_filenames.root_path<br/>**Variable d'environnement** : DOC.OTHER_ROOT_FILENAMES.ROOT_PATH | Ce fichier contient les variables enfants de la famille. | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` | `unique` |
| **<a id="doc.other_root_filenames.filename" name="doc.other_root_filenames.filename">doc.other_root_filenames.filename</a>**<br/>**Ligne de commande** : <br/>--doc.other_root_filenames.filename<br/>**Variable d'environnement** : DOC.OTHER_ROOT_FILENAMES.FILENAME | Nom du fichier. | [`UNIX filename`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | •&nbsp;le nom de fichier peut être une chemin relatif<br/>•&nbsp;type de fichier autorisé: "file". |
### Documentation des variables et journal de changements
@ -51,7 +48,7 @@ include_toc: true
| **<a id="doc.tabulars.without_family" name="doc.tabulars.without_family">doc.tabulars.without_family</a>**<br/>**Ligne de commande** : <br/>•&nbsp;-df, --doc.tabulars.without_family<br/>•&nbsp;-ndf, --doc.tabulars.no-without_family<br/>**Variable d'environnement** : DOC.TABULARS.WITHOUT_FAMILY | Ne pas ajouter les familles dans la documentation. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | |
| **<a id="doc.tabulars.with_commandline" name="doc.tabulars.with_commandline">doc.tabulars.with_commandline</a>**<br/>**Ligne de commande** : <br/>•&nbsp;-dw, --doc.tabulars.with_commandline<br/>•&nbsp;-ndw, --doc.tabulars.no-with_commandline<br/>**Variable d'environnement** : DOC.TABULARS.WITH_COMMANDLINE | Ajoute les informations de la ligne de commande dans la documentation. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | |
| **<a id="doc.tabulars.with_environment" name="doc.tabulars.with_environment">doc.tabulars.with_environment</a>**<br/>**Ligne de commande** : <br/>•&nbsp;-de, --doc.tabulars.with_environment<br/>•&nbsp;-nde, --doc.tabulars.no-with_environment<br/>**Variable d'environnement** : DOC.TABULARS.WITH_ENVIRONMENT | Ajoute les informations de variable d&#x27;environnement dans la documentation. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | | |
| **<a id="doc.tabulars.environment_prefix" name="doc.tabulars.environment_prefix">doc.tabulars.environment_prefix</a>**<br/>**Ligne de commande** : -dv, --doc.tabulars.environment_prefix<br/>**Variable d'environnement** : DOC.TABULARS.ENVIRONMENT_PREFIX | Préfixe du nom des variables d&#x27;environnement. | ROUGAIL | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | *`désactivé`*<br/>**Désactivé** : si "main_namespace" n'est pas défini ou "[Ajoute les informations de variable d&#x27;environnement dans la documentation](#doc.tabulars.with_environment)" est false | Doit seulement utilise des caractères en majuscule. |
| **<a id="doc.tabulars.environment_prefix" name="doc.tabulars.environment_prefix">doc.tabulars.environment_prefix</a>**<br/>**Ligne de commande** : <br/>-dv, --doc.tabulars.environment_prefix<br/>**Variable d'environnement** : DOC.TABULARS.ENVIRONMENT_PREFIX | Préfixe du nom des variables d&#x27;environnement. | ROUGAIL | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | *`désactivé`*<br/>**Désactivé** : si "main_namespace" n'est pas défini ou "[Ajoute les informations de variable d&#x27;environnement dans la documentation](#doc.tabulars.with_environment)" est false | Doit seulement utilise des caractères en majuscule. |
### Documentation du journal des changements
@ -61,9 +58,9 @@ include_toc: true
> *`désactivé`*\
> **Désactivé** : changelog n'est pas défini dans "[Contenu généré](#doc.contents)"
| Variable | Description | Type |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| **<a id="doc.changelog.previous_json_file" name="doc.changelog.previous_json_file">doc.changelog.previous_json_file</a>**<br/>**Ligne de commande** : -dp, --doc.changelog.previous_json_file<br/>**Variable d'environnement** : DOC.CHANGELOG.PREVIOUS_JSON_FILE | Précédent fichier de description au format JSON.<br/>Pour générer le journal des changements, vous devez comparer l&#x27;ancienne liste des variables (au format json) avec les variables courantes. | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` |
| Variable | Description | Type |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| **<a id="doc.changelog.previous_json_file" name="doc.changelog.previous_json_file">doc.changelog.previous_json_file</a>**<br/>**Ligne de commande** : <br/>-dp, --doc.changelog.previous_json_file<br/>**Variable d'environnement** : DOC.CHANGELOG.PREVIOUS_JSON_FILE | Précédent fichier de description au format JSON.<br/>Pour générer le journal des changements, vous devez comparer l&#x27;ancienne liste des variables (au format json) avec les variables courantes. | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` |
### Configuration des exemples
@ -76,6 +73,6 @@ include_toc: true
| Variable | Description | Valeur par défaut | Type | Contrôle des accès |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|---------------------|---------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="doc.examples.comment" name="doc.examples.comment">doc.examples.comment</a>**<br/>**Ligne de commande** : <br/>•&nbsp;-dx, --doc.examples.comment<br/>•&nbsp;-ndx, --doc.examples.no-comment<br/>**Variable d'environnement** : DOC.EXAMPLES.COMMENT | Ajouter la description des variables et des familles lorsqu&#x27;on génère des exemples. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | |
| **<a id="doc.examples.comment_column" name="doc.examples.comment_column">doc.examples.comment_column</a>**<br/>**Ligne de commande** : --doc.examples.comment_column<br/>**Variable d'environnement** : DOC.EXAMPLES.COMMENT_COLUMN | Commentaire dans les exemples commence à la colonne. | 30 | [`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | *`désactivé`*<br/>**Désactivé** : lorsque la variable "[Ajouter la description des variables et des familles lorsqu&#x27;on génère des exemples](#doc.examples.comment)" a la valeur "false" |
| **<a id="doc.examples.comment_column" name="doc.examples.comment_column">doc.examples.comment_column</a>**<br/>**Ligne de commande** : <br/>--doc.examples.comment_column<br/>**Variable d'environnement** : DOC.EXAMPLES.COMMENT_COLUMN | Commentaire dans les exemples commence à la colonne. | 30 | [`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `obligatoire` | *`désactivé`*<br/>**Désactivé** : lorsque la variable "[Ajouter la description des variables et des familles lorsqu&#x27;on génère des exemples](#doc.examples.comment)" a la valeur "false" |

31
README.md
View file

@ -15,13 +15,12 @@ include_toc: true
| Variable | Description | Default value | Type | Access control | Validator |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|-----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="doc.output_format" name="doc.output_format">doc.output_format</a>**<br/>**Command line**: -do, --doc.output_format<br/>**Environment variable**: DOC.OUTPUT_FORMAT | The output format of the generated documentation. | console | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | **Choices**: <br/>•&nbsp;console<br/>•&nbsp;asciidoc<br/>•&nbsp;html<br/>•&nbsp;github<br/>•&nbsp;gitlab<br/>•&nbsp;json |
| **<a id="doc.tabular_template" name="doc.tabular_template">doc.tabular_template</a>**<br/>**Command line**: -dm, --doc.tabular_template<br/>**Environment variable**: DOC.TABULAR_TEMPLATE | Generate document with this tabular model.<br/>The variables are documented with a tabular view. A template selection allows you to choose the content of each column. | two_columns | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | *`disabled`*<br/>**Disabled**: "[The output format of the generated documentation](#doc.output_format)" in json is not compatible with this variable<br/> | **Choices**: <br/>•&nbsp;two_columns<br/>•&nbsp;three_columns<br/>•&nbsp;four_columns<br/>•&nbsp;five_columns<br/>•&nbsp;six_columns |
| **<a id="doc.contents" name="doc.contents">doc.contents</a>**<br/>**Command line**: -dc, --doc.contents<br/>**Environment variable**: DOC.CONTENTS | Generated content.<br/>You can generate three type of document. All variables (&quot;variables&quot;), an example file in YAML format (&quot;example&quot;) or change log (&quot;changelog&quot;). | •&nbsp;variables | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` `mandatory` | *`hidden`*<br/>**Hidden**: "[The output format of the generated documentation](#doc.output_format)" in json is not compatible with changelog or example "[Generated content](#doc.contents)"<br/> | `unique`<br/>**Choices**: <br/>•&nbsp;variables<br/>•&nbsp;example<br/>•&nbsp;changelog |
| **<a id="doc.title_level" name="doc.title_level">doc.title_level</a>**<br/>**Command line**: -dt, --doc.title_level<br/>**Environment variable**: DOC.TITLE_LEVEL | Starting title level. | 1 | [`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | |
| **<a id="doc.output_format" name="doc.output_format">doc.output_format</a>**<br/>**Command line**: <br/>-do, --doc.output_format<br/>**Environment variable**: DOC.OUTPUT_FORMAT | The output format of the generated documentation. | console | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | **Choices**: <br/>•&nbsp;console<br/>•&nbsp;asciidoc<br/>•&nbsp;html<br/>•&nbsp;github<br/>•&nbsp;gitlab<br/>•&nbsp;json |
| **<a id="doc.tabular_template" name="doc.tabular_template">doc.tabular_template</a>**<br/>**Command line**: <br/>-dm, --doc.tabular_template<br/>**Environment variable**: DOC.TABULAR_TEMPLATE | Generate document with this tabular model.<br/>The variables are documented with a tabular view. A template selection allows you to choose the content of each column. | two_columns | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | *`disabled`*<br/>**Disabled**: "[The output format of the generated documentation](#doc.output_format)" in json is not compatible with this variable<br/> | **Choices**: <br/>•&nbsp;two_columns<br/>•&nbsp;three_columns<br/>•&nbsp;four_columns<br/>•&nbsp;five_columns<br/>•&nbsp;six_columns |
| **<a id="doc.contents" name="doc.contents">doc.contents</a>**<br/>**Command line**: <br/>-dc, --doc.contents<br/>**Environment variable**: DOC.CONTENTS | Generated content.<br/>You can generate three type of document. All variables (&quot;variables&quot;), an example file in YAML format (&quot;example&quot;) or change log (&quot;changelog&quot;). | •&nbsp;variables | [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` `mandatory` | *`hidden`*<br/>**Hidden**: "[The output format of the generated documentation](#doc.output_format)" in json is not compatible with changelog or example "[Generated content](#doc.contents)"<br/> | `unique`<br/>**Choices**: <br/>•&nbsp;variables<br/>•&nbsp;example<br/>•&nbsp;changelog |
| **<a id="doc.title_level" name="doc.title_level">doc.title_level</a>**<br/>**Command line**: <br/>-dt, --doc.title_level<br/>**Environment variable**: DOC.TITLE_LEVEL | Starting title level. | 1 | [`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | |
| **<a id="doc.default_values" name="doc.default_values">doc.default_values</a>**<br/>**Command line**: <br/>•&nbsp;--doc.default_values<br/>•&nbsp;--doc.no-default_values<br/>**Environment variable**: DOC.DEFAULT_VALUES | Modify values to document all variables.<br/>To document leadership or dynamic family variables, it is sometimes necessary to generate values, which can change the values in the configuration. Be careful if you reuse this configuration. | true | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | |
| **<a id="doc.true_color" name="doc.true_color">doc.true_color</a>**<br/>**Command line**: <br/>•&nbsp;--doc.true_color<br/>•&nbsp;--doc.no-true_color<br/>**Environment variable**: DOC.TRUE_COLOR | Display documentation in console always with true color terminal. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | *`disabled`*<br/>**Disabled**: when the variable "[The output format of the generated documentation](#doc.output_format)" hasn't the value "console" | |
| **<a id="doc.root" name="doc.root">doc.root</a>**<br/>**Command line**: -dr, --doc.root<br/>**Environment variable**: DOC.ROOT | Document the child variables of the family.<br/>By default, all accessible variables are included in the documentation. It is possible to define the family from which the documentation should be generated. | | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) | | |
### The variables in this family are documented in another file
@ -29,14 +28,12 @@ include_toc: true
>
> If you separate the variables into different files, the links between the variables will break. Therefore, you must define different filenames for the files containing these variables.\
> This family contains lists of variable blocks.\
> **Path**: doc.other_root_filenames\
> *`disabled`*\
> **Disabled**: when the variable "[Document the child variables of the family](#doc.root)" has the value "null"
> **Path**: doc.other_root_filenames
| Variable | Description | Type | Validator |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| **<a id="doc.other_root_filenames.root_path" name="doc.other_root_filenames.root_path">doc.other_root_filenames.root_path</a>**<br/>**Command line**: --doc.other_root_filenames.root_path<br/>**Environment variable**: DOC.OTHER_ROOT_FILENAMES.ROOT_PATH | This file contains child variables of the family. | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` | `unique` |
| **<a id="doc.other_root_filenames.filename" name="doc.other_root_filenames.filename">doc.other_root_filenames.filename</a>**<br/>**Command line**: --doc.other_root_filenames.filename<br/>**Environment variable**: DOC.OTHER_ROOT_FILENAMES.FILENAME | Name of the file. | [`UNIX filename`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | •&nbsp;this filename could be a relative path<br/>•&nbsp;file type allowed: "file". |
| Variable | Description | Type | Validator |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| **<a id="doc.other_root_filenames.root_path" name="doc.other_root_filenames.root_path">doc.other_root_filenames.root_path</a>**<br/>**Command line**: <br/>--doc.other_root_filenames.root_path<br/>**Environment variable**: DOC.OTHER_ROOT_FILENAMES.ROOT_PATH | This file contains child variables of the family. | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` | `unique` |
| **<a id="doc.other_root_filenames.filename" name="doc.other_root_filenames.filename">doc.other_root_filenames.filename</a>**<br/>**Command line**: <br/>--doc.other_root_filenames.filename<br/>**Environment variable**: DOC.OTHER_ROOT_FILENAMES.FILENAME | Name of the file. | [`UNIX filename`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | •&nbsp;this filename could be a relative path<br/>•&nbsp;file type allowed: "file". |
### Variables and changelog documentation
@ -51,7 +48,7 @@ include_toc: true
| **<a id="doc.tabulars.without_family" name="doc.tabulars.without_family">doc.tabulars.without_family</a>**<br/>**Command line**: <br/>•&nbsp;-df, --doc.tabulars.without_family<br/>•&nbsp;-ndf, --doc.tabulars.no-without_family<br/>**Environment variable**: DOC.TABULARS.WITHOUT_FAMILY | Do not add families in documentation. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | |
| **<a id="doc.tabulars.with_commandline" name="doc.tabulars.with_commandline">doc.tabulars.with_commandline</a>**<br/>**Command line**: <br/>•&nbsp;-dw, --doc.tabulars.with_commandline<br/>•&nbsp;-ndw, --doc.tabulars.no-with_commandline<br/>**Environment variable**: DOC.TABULARS.WITH_COMMANDLINE | Add command line informations in documentation. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | |
| **<a id="doc.tabulars.with_environment" name="doc.tabulars.with_environment">doc.tabulars.with_environment</a>**<br/>**Command line**: <br/>•&nbsp;-de, --doc.tabulars.with_environment<br/>•&nbsp;-nde, --doc.tabulars.no-with_environment<br/>**Environment variable**: DOC.TABULARS.WITH_ENVIRONMENT | Add environment variable informations in documentation. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | | |
| **<a id="doc.tabulars.environment_prefix" name="doc.tabulars.environment_prefix">doc.tabulars.environment_prefix</a>**<br/>**Command line**: -dv, --doc.tabulars.environment_prefix<br/>**Environment variable**: DOC.TABULARS.ENVIRONMENT_PREFIX | Environment variables prefix name. | ROUGAIL | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | *`disabled`*<br/>**Disabled**: if "main_namespace" is not set or "[Add environment variable informations in documentation](#doc.tabulars.with_environment)" is false | Should only use uppercase characters. |
| **<a id="doc.tabulars.environment_prefix" name="doc.tabulars.environment_prefix">doc.tabulars.environment_prefix</a>**<br/>**Command line**: <br/>-dv, --doc.tabulars.environment_prefix<br/>**Environment variable**: DOC.TABULARS.ENVIRONMENT_PREFIX | Environment variables prefix name. | ROUGAIL | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | *`disabled`*<br/>**Disabled**: if "main_namespace" is not set or "[Add environment variable informations in documentation](#doc.tabulars.with_environment)" is false | Should only use uppercase characters. |
### Changelog documentation
@ -61,9 +58,9 @@ include_toc: true
> *`disabled`*\
> **Disabled**: if changelog in not in "[Generated content](#doc.contents)"
| Variable | Description | Type |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| **<a id="doc.changelog.previous_json_file" name="doc.changelog.previous_json_file">doc.changelog.previous_json_file</a>**<br/>**Command line**: -dp, --doc.changelog.previous_json_file<br/>**Environment variable**: DOC.CHANGELOG.PREVIOUS_JSON_FILE | Previous description file in JSON format.<br/>To generate the changelog, you need to compare the old list of variables (in json format) with the current variables. | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` |
| Variable | Description | Type |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| **<a id="doc.changelog.previous_json_file" name="doc.changelog.previous_json_file">doc.changelog.previous_json_file</a>**<br/>**Command line**: <br/>-dp, --doc.changelog.previous_json_file<br/>**Environment variable**: DOC.CHANGELOG.PREVIOUS_JSON_FILE | Previous description file in JSON format.<br/>To generate the changelog, you need to compare the old list of variables (in json format) with the current variables. | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` |
### Examples configuration
@ -76,6 +73,6 @@ include_toc: true
| Variable | Description | Default value | Type | Access control |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="doc.examples.comment" name="doc.examples.comment">doc.examples.comment</a>**<br/>**Command line**: <br/>•&nbsp;-dx, --doc.examples.comment<br/>•&nbsp;-ndx, --doc.examples.no-comment<br/>**Environment variable**: DOC.EXAMPLES.COMMENT | Add description of variables and families when generate examples. | false | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | |
| **<a id="doc.examples.comment_column" name="doc.examples.comment_column">doc.examples.comment_column</a>**<br/>**Command line**: --doc.examples.comment_column<br/>**Environment variable**: DOC.EXAMPLES.COMMENT_COLUMN | Comment in examples starts at column. | 30 | [`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | *`disabled`*<br/>**Disabled**: when the variable "[Add description of variables and families when generate examples](#doc.examples.comment)" has the value "false" |
| **<a id="doc.examples.comment_column" name="doc.examples.comment_column">doc.examples.comment_column</a>**<br/>**Command line**: <br/>--doc.examples.comment_column<br/>**Environment variable**: DOC.EXAMPLES.COMMENT_COLUMN | Comment in examples starts at column. | 30 | [`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | *`disabled`*<br/>**Disabled**: when the variable "[Add description of variables and families when generate examples](#doc.examples.comment)" has the value "false" |

188
locale/fr/LC_MESSAGES/rougail_output_doc.po
View file

@ -5,8 +5,8 @@
msgid ""
msgstr ""
"Project-Id-Version: \n"
"POT-Creation-Date: 2025-12-22 08:53+0100\n"
"PO-Revision-Date: 2025-12-22 08:54+0100\n"
"POT-Creation-Date: 2026-01-04 19:14+0100\n"
"PO-Revision-Date: 2026-01-04 19:15+0100\n"
"Last-Translator: \n"
"Language-Team: \n"
"Language: fr\n"
@ -32,27 +32,27 @@ msgstr "lorsque l'identifiant est \"{0}\""
msgid "when the identifier is not \"{0}\""
msgstr "lorsque l'identifiant n'est pas \"{0}\""
#: src/rougail/output_doc/changelog.py:147
#: src/rougail/output_doc/changelog.py:137
msgid "New variable"
msgstr "Nouvelle variable"
#: src/rougail/output_doc/changelog.py:149
#: src/rougail/output_doc/changelog.py:139
msgid "New variables"
msgstr "Nouvelles variables"
#: src/rougail/output_doc/changelog.py:163
#: src/rougail/output_doc/changelog.py:153
msgid "Modified variable"
msgstr "Variable modifiée"
#: src/rougail/output_doc/changelog.py:165
#: src/rougail/output_doc/changelog.py:155
msgid "Modified variables"
msgstr "Variables modifiées"
#: src/rougail/output_doc/changelog.py:179
#: src/rougail/output_doc/changelog.py:169
msgid "Deleted variable"
msgstr "Variable supprimée"
#: src/rougail/output_doc/changelog.py:181
#: src/rougail/output_doc/changelog.py:171
msgid "Deleted variables"
msgstr "Variables supprimées"
@ -64,15 +64,15 @@ msgstr "niveau dupliqué pour rougail-doc pour {0} \"{1}\": {2} et {3}"
msgid "duplicated name \"{0}\" in rougail-output-doc"
msgstr "nom dupliqué \"{0}\" dans rougail-output-doc"
#: src/rougail/output_doc/config.py:117
#: src/rougail/output_doc/config.py:118
msgid "is true if doc is activate"
msgstr "est true si doc est activé"
#: src/rougail/output_doc/config.py:120
#: src/rougail/output_doc/config.py:121
msgid "Generate documentation from structural files"
msgstr "Générer la documentation depuis les fichiers de structure"
#: src/rougail/output_doc/config.py:121
#: src/rougail/output_doc/config.py:122
msgid ""
"The structural files contain all the information related to the variables. "
"This output generates the documentation for all or some of these variables."
@ -81,19 +81,19 @@ msgstr ""
"variables. Cette sortie génère la documentation pour tout ou partie de ces "
"variables."
#: src/rougail/output_doc/config.py:126
#: src/rougail/output_doc/config.py:127
msgid "if doc is not set in \"step.output\""
msgstr "si doc n'est pas spécifié dans \"step.output\""
#: src/rougail/output_doc/config.py:129
#: src/rougail/output_doc/config.py:130
msgid "The output format of the generated documentation"
msgstr "Le format de sortie de la documentation générée"
#: src/rougail/output_doc/config.py:138
#: src/rougail/output_doc/config.py:139
msgid "Generate document with this tabular model"
msgstr "Génère la documentation avec ce modèle de tableau"
#: src/rougail/output_doc/config.py:139
#: src/rougail/output_doc/config.py:140
msgid ""
"The variables are documented with a tabular view. A template selection "
"allows you to choose the content of each column."
@ -101,15 +101,15 @@ msgstr ""
"Les variables sont documentées avec une vue tableau. Une sélection de modèle "
"vous permet de choisir le contenu de chaque colonne."
#: src/rougail/output_doc/config.py:147
#: src/rougail/output_doc/config.py:148
msgid "\"_.output_format\" in json is not compatible with this variable"
msgstr "\"_.output_format\" en json n\\'est pas compatible avec cette variable"
#: src/rougail/output_doc/config.py:154
#: src/rougail/output_doc/config.py:155
msgid "Generated content"
msgstr "Contenu généré"
#: src/rougail/output_doc/config.py:155
#: src/rougail/output_doc/config.py:156
msgid ""
"You can generate three type of document. All variables (\"variables\"), an "
"example file in YAML format (\"example\") or change log (\"changelog\")."
@ -118,7 +118,7 @@ msgstr ""
"(\"variables\"), un exemple de fichier au format YAML (\"example\") ou le "
"journal des changements (\"changelog\")."
#: src/rougail/output_doc/config.py:168
#: src/rougail/output_doc/config.py:169
msgid ""
"\"_.output_format\" in json is not compatible with changelog or example "
"\"_.contents\""
@ -126,15 +126,15 @@ msgstr ""
"\"_.output_format\" en json n'est pas compatible avec \"_.contents\" "
"changelog or example"
#: src/rougail/output_doc/config.py:171
#: src/rougail/output_doc/config.py:172
msgid "Starting title level"
msgstr "Niveau de titre de départ"
#: src/rougail/output_doc/config.py:176
#: src/rougail/output_doc/config.py:177
msgid "Modify values to document all variables"
msgstr "Modifier les valeurs pour documenter toutes les variables"
#: src/rougail/output_doc/config.py:177
#: src/rougail/output_doc/config.py:178
msgid ""
"To document leadership or dynamic family variables, it is sometimes "
"necessary to generate values, which can change the values in the "
@ -145,31 +145,17 @@ msgstr ""
"valeurs de la configuration. Soyez vigilent si vous réutilisez cette "
"configuration."
#: src/rougail/output_doc/config.py:181
#: src/rougail/output_doc/config.py:182
msgid "Display documentation in console always with true color terminal"
msgstr ""
"Afficher la documentation dans la console en permanence avec un terminal en "
"couleurs réelles"
#: src/rougail/output_doc/config.py:188
msgid "Document the child variables of the family"
msgstr "Documenter les variables enfants de cette famille"
#: src/rougail/output_doc/config.py:189
msgid ""
"By default, all accessible variables are included in the documentation. It "
"is possible to define the family from which the documentation should be "
"generated."
msgstr ""
"Par défaut, toute les variables accessibles sont incluent dans la "
"documentation. Il est possible de définir une famille a partir de laquelle "
"la documentation doit être générée."
#: src/rougail/output_doc/config.py:194
msgid "The variables in this family are documented in another file"
msgstr "Les variables pour cette famille sont documentés dans un autre fichier"
#: src/rougail/output_doc/config.py:195
#: src/rougail/output_doc/config.py:190
msgid ""
"If you separate the variables into different files, the links between the "
"variables will break. Therefore, you must define different filenames for the "
@ -179,19 +165,19 @@ msgstr ""
"variables va être cassé. Dans ce cas, vous devez définit différents nom de "
"fichiers pour les fichiers contenant ces variables."
#: src/rougail/output_doc/config.py:202
#: src/rougail/output_doc/config.py:194
msgid "This file contains child variables of the family"
msgstr "Ce fichier contient les variables enfants de la famille"
#: src/rougail/output_doc/config.py:206
#: src/rougail/output_doc/config.py:198
msgid "Name of the file"
msgstr "Nom du fichier"
#: src/rougail/output_doc/config.py:214
#: src/rougail/output_doc/config.py:206
msgid "Variables and changelog documentation"
msgstr "Documentation des variables et journal de changements"
#: src/rougail/output_doc/config.py:219
#: src/rougail/output_doc/config.py:211
msgid ""
"if \"_.output_format\" is json or \"_.contents\" hasn't variables or "
"changelog"
@ -199,45 +185,45 @@ msgstr ""
"si \"_.output_format\" en json ou si \"_.contents\" n'est pas variables ou "
"changelog"
#: src/rougail/output_doc/config.py:222
#: src/rougail/output_doc/config.py:214
msgid "Do not add families in documentation"
msgstr "Ne pas ajouter les familles dans la documentation"
#: src/rougail/output_doc/config.py:227
#: src/rougail/output_doc/config.py:219
msgid "Add command line informations in documentation"
msgstr "Ajoute les informations de la ligne de commande dans la documentation"
#: src/rougail/output_doc/config.py:232
#: src/rougail/output_doc/config.py:224
msgid "Add environment variable informations in documentation"
msgstr ""
"Ajoute les informations de variable d'environnement dans la documentation"
#: src/rougail/output_doc/config.py:237
#: src/rougail/output_doc/config.py:229
msgid "Environment variables prefix name"
msgstr "Préfixe du nom des variables d'environnement"
#: src/rougail/output_doc/config.py:244
#: src/rougail/output_doc/config.py:236
msgid "should only use uppercase characters"
msgstr "doit seulement utilise des caractères en majuscule"
#: src/rougail/output_doc/config.py:249
#: src/rougail/output_doc/config.py:241
msgid "if \"main_namespace\" is not set or \"_.with_environment\" is false"
msgstr ""
"si \"main_namespace\" n'est pas défini ou \"_.with_environment\" est false"
#: src/rougail/output_doc/config.py:252
#: src/rougail/output_doc/config.py:244
msgid "Changelog documentation"
msgstr "Documentation du journal des changements"
#: src/rougail/output_doc/config.py:257
#: src/rougail/output_doc/config.py:249
msgid "if changelog in not in \"_.contents\""
msgstr "changelog n'est pas défini dans \"_.contents\""
#: src/rougail/output_doc/config.py:260
#: src/rougail/output_doc/config.py:252
msgid "Previous description file in JSON format"
msgstr "Précédent fichier de description au format JSON"
#: src/rougail/output_doc/config.py:261
#: src/rougail/output_doc/config.py:253
msgid ""
"To generate the changelog, you need to compare the old list of variables (in "
"json format) with the current variables."
@ -245,118 +231,118 @@ msgstr ""
"Pour générer le journal des changements, vous devez comparer l'ancienne "
"liste des variables (au format json) avec les variables courantes."
#: src/rougail/output_doc/config.py:265
#: src/rougail/output_doc/config.py:257
msgid "Examples configuration"
msgstr "Configuration des exemples"
#: src/rougail/output_doc/config.py:270
#: src/rougail/output_doc/config.py:262
msgid "if example is not in \"_.contents\""
msgstr "si example n'est pas défini dans \"_.contents\""
#: src/rougail/output_doc/config.py:273
#: src/rougail/output_doc/config.py:265
msgid "Add description of variables and families when generate examples"
msgstr ""
"Ajouter la description des variables et des familles lorsqu'on génère des "
"exemples"
#: src/rougail/output_doc/config.py:278
#: src/rougail/output_doc/config.py:270
msgid "Comment in examples starts at column"
msgstr "Commentaire dans les exemples commence à la colonne"
#: src/rougail/output_doc/doc.py:329
#: src/rougail/output_doc/doc.py:354
msgid "This family contains lists of variable blocks"
msgstr "Cette famille contient des listes de bloc de variable"
#: src/rougail/output_doc/doc.py:339
#: src/rougail/output_doc/doc.py:364
msgid "This family builds families dynamically"
msgstr "Cette famille construit des familles dynamiquement"
#: src/rougail/output_doc/doc.py:353
#: src/rougail/output_doc/doc.py:378
msgid "Default"
msgstr "Défaut"
#: src/rougail/output_doc/doc.py:371
#: src/rougail/output_doc/doc.py:396
msgid "Example"
msgstr "Exemple"
#: src/rougail/output_doc/doc.py:374
#: src/rougail/output_doc/doc.py:399
msgid "Examples"
msgstr "Exemples"
#: src/rougail/output_doc/doc.py:383
#: src/rougail/output_doc/doc.py:408
msgid "Tag"
msgstr "Étiquette"
#: src/rougail/output_doc/doc.py:386
#: src/rougail/output_doc/doc.py:411
msgid "Tags"
msgstr "Étiquettes"
#: src/rougail/output_doc/doc.py:418
#: src/rougail/output_doc/doc.py:443
msgid "No attribute \"description\" for \"{0}\" in {1}"
msgstr "Aucun attribut \"description\" pour \"{0}\" dans {1}"
#: src/rougail/output_doc/doc.py:553
#: src/rougail/output_doc/doc.py:578
msgid "text based with regular expressions \"{0}\""
msgstr "texte avec expression rationnelle \"{0}\""
#: src/rougail/output_doc/doc.py:557
#: src/rougail/output_doc/doc.py:582
#: src/rougail/output_doc/tabular/six_columns.py:65
msgid "Validator"
msgstr "Validateur"
#: src/rougail/output_doc/doc.py:560
#: src/rougail/output_doc/doc.py:585
msgid "Validators"
msgstr "Validateurs"
#: src/rougail/output_doc/doc.py:569
#: src/rougail/output_doc/doc.py:594
msgid "Choices"
msgstr "Choix"
#: src/rougail/output_doc/doc.py:672
#: src/rougail/output_doc/doc.py:697
msgid "the value of the identifier"
msgstr "la valeur de l'identifiant"
#: src/rougail/output_doc/doc.py:676
#: src/rougail/output_doc/doc.py:701
msgid "the value of the {0}"
msgstr "la valeur de l'{0}"
#: src/rougail/output_doc/doc.py:685
#: src/rougail/output_doc/doc.py:710
msgid "depends on a calculation"
msgstr "dépend d'un calcul"
#: src/rougail/output_doc/doc.py:691
#: src/rougail/output_doc/doc.py:716
msgid "\"{0}\" is a calculation for {1} but has no description in {2}"
msgstr "\"{0}\" est un calcul pour {1} mais n'a pas de description dans {2}"
#: src/rougail/output_doc/doc.py:719
#: src/rougail/output_doc/doc.py:744
msgid "the value of the variable \"{0}\""
msgstr "la valeur de la variable \"{0}\""
#: src/rougail/output_doc/doc.py:721
#: src/rougail/output_doc/doc.py:746
msgid "the value of the variable \"{0}\" if it is defined"
msgstr "la valeur de la variable \"{0}\" si elle est définie"
#: src/rougail/output_doc/doc.py:741
#: src/rougail/output_doc/doc.py:766
msgid "the value of an undocumented variable"
msgstr "la valeur d'une variable non documentée"
#: src/rougail/output_doc/doc.py:744
#: src/rougail/output_doc/doc.py:769
msgid "the values of undocumented variables"
msgstr "les valeurs de variables non documentées"
#: src/rougail/output_doc/doc.py:767
#: src/rougail/output_doc/doc.py:792
msgid "(from an undocumented variable)"
msgstr "(issue d'une variable non documentée)"
#: src/rougail/output_doc/doc.py:775
#: src/rougail/output_doc/doc.py:800
msgid "{0} (from an undocumented variable)"
msgstr "{0} (issue d'une variable non documentée)"
#: src/rougail/output_doc/doc.py:779 src/rougail/output_doc/doc.py:831
#: src/rougail/output_doc/doc.py:804 src/rougail/output_doc/doc.py:856
msgid "depends on an undocumented variable"
msgstr "dépends d'une variable non documentée"
#: src/rougail/output_doc/doc.py:853
#: src/rougail/output_doc/doc.py:878
msgid ""
"when the variable \"{{0}}\" is defined, accessible and hasn't the value "
"\"{0}\""
@ -364,43 +350,43 @@ msgstr ""
"lorsque la variable \"{{0}}\" est définie, accessible et n'a pas la valeur "
"\"{0}\""
#: src/rougail/output_doc/doc.py:857
#: src/rougail/output_doc/doc.py:882
msgid "when the variable \"{{0}}\" is defined and hasn't the value \"{0}\""
msgstr "lorsque la variable \"{{0}}\" est définie et n'a pas la valeur \"{0}\""
#: src/rougail/output_doc/doc.py:861
#: src/rougail/output_doc/doc.py:886
msgid "when the variable \"{{0}}\" is accessible and hasn't the value \"{0}\""
msgstr ""
"lorsque la variable \"{{0}}\" est accessible et n'a pas la valeur \"{0}\""
#: src/rougail/output_doc/doc.py:863
#: src/rougail/output_doc/doc.py:888
msgid "when the variable \"{{0}}\" hasn't the value \"{0}\""
msgstr "lorsque la variable \"{{0}}\" n'a pas la valeur \"{0}\""
#: src/rougail/output_doc/doc.py:867
#: src/rougail/output_doc/doc.py:892
msgid ""
"when the variable \"{{0}}\" is defined, is accessible and has the value "
"\"{0}\""
msgstr ""
"lorsque la variable \"{{0}}\" est définie, accessible et a la valeur \"{0}\""
#: src/rougail/output_doc/doc.py:871
#: src/rougail/output_doc/doc.py:896
msgid "when the variable \"{{0}}\" is defined and has the value \"{0}\""
msgstr "lorsque la variable \"{{0}}\" est définie et a la valeur \"{0}\""
#: src/rougail/output_doc/doc.py:875
#: src/rougail/output_doc/doc.py:900
msgid "when the variable \"{{0}}\" is accessible and has the value \"{0}\""
msgstr "lorsque la variable \"{{0}}\" est accessible et a la valeur \"{0}\""
#: src/rougail/output_doc/doc.py:877
#: src/rougail/output_doc/doc.py:902
msgid "when the variable \"{{0}}\" has the value \"{0}\""
msgstr "lorsque la variable \"{{0}}\" a la valeur \"{0}\""
#: src/rougail/output_doc/example.py:45
#: src/rougail/output_doc/example.py:62
msgid "Example with mandatory variables not filled in"
msgstr "Exemple avec des variables obligatoire non renseignée"
#: src/rougail/output_doc/example.py:52
#: src/rougail/output_doc/example.py:69
msgid "Example with all variables modifiable"
msgstr "Exemple avec toutes les variables modifiable"
@ -438,24 +424,36 @@ msgstr "Ligne de commande"
msgid "Environment variable"
msgstr "Variable d'environnement"
#: src/rougail/output_doc/utils.py:458
#: src/rougail/output_doc/utils.py:437
msgid "Path"
msgstr "Chemin"
#: src/rougail/output_doc/utils.py:468
#: src/rougail/output_doc/utils.py:447
msgid "Identifiers"
msgstr "Identifiants"
#: src/rougail/output_doc/utils.py:684 src/rougail/output_doc/utils.py:693
#: src/rougail/output_doc/utils.py:699 src/rougail/output_doc/utils.py:705
#: src/rougail/output_doc/utils.py:709
#: src/rougail/output_doc/utils.py:663 src/rougail/output_doc/utils.py:672
#: src/rougail/output_doc/utils.py:678 src/rougail/output_doc/utils.py:684
#: src/rougail/output_doc/utils.py:688
msgid "(default)"
msgstr "(défaut)"
#: src/rougail/output_doc/utils.py:960
#: src/rougail/output_doc/utils.py:940
msgid "{0}: {1}"
msgstr "{0} : {1}"
#~ msgid "Document the child variables of the family"
#~ msgstr "Documenter les variables enfants de cette famille"
#~ msgid ""
#~ "By default, all accessible variables are included in the documentation. "
#~ "It is possible to define the family from which the documentation should "
#~ "be generated."
#~ msgstr ""
#~ "Par défaut, toute les variables accessibles sont incluent dans la "
#~ "documentation. Il est possible de définir une famille a partir de "
#~ "laquelle la documentation doit être générée."
#~ msgid "variables is not selected in \"_.contents\""
#~ msgstr "variables n'est pas sélectionné dans \"_.contents\""

138
locale/rougail_output_doc.pot
View file

@ -5,7 +5,7 @@
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 2025-12-23 21:35+0100\n"
"POT-Creation-Date: 2026-01-04 19:15+0100\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
@ -31,27 +31,27 @@ msgstr ""
msgid "when the identifier is not \"{0}\""
msgstr ""
#: src/rougail/output_doc/changelog.py:147
#: src/rougail/output_doc/changelog.py:137
msgid "New variable"
msgstr ""
#: src/rougail/output_doc/changelog.py:149
#: src/rougail/output_doc/changelog.py:139
msgid "New variables"
msgstr ""
#: src/rougail/output_doc/changelog.py:163
#: src/rougail/output_doc/changelog.py:153
msgid "Modified variable"
msgstr ""
#: src/rougail/output_doc/changelog.py:165
#: src/rougail/output_doc/changelog.py:155
msgid "Modified variables"
msgstr ""
#: src/rougail/output_doc/changelog.py:179
#: src/rougail/output_doc/changelog.py:169
msgid "Deleted variable"
msgstr ""
#: src/rougail/output_doc/changelog.py:181
#: src/rougail/output_doc/changelog.py:171
msgid "Deleted variables"
msgstr ""
@ -124,223 +124,215 @@ msgid "Display documentation in console always with true color terminal"
msgstr ""
#: src/rougail/output_doc/config.py:189
msgid "Document the child variables of the family"
msgstr ""
#: src/rougail/output_doc/config.py:190
msgid "By default, all accessible variables are included in the documentation. It is possible to define the family from which the documentation should be generated."
msgstr ""
#: src/rougail/output_doc/config.py:195
msgid "The variables in this family are documented in another file"
msgstr ""
#: src/rougail/output_doc/config.py:196
#: src/rougail/output_doc/config.py:190
msgid "If you separate the variables into different files, the links between the variables will break. Therefore, you must define different filenames for the files containing these variables."
msgstr ""
#: src/rougail/output_doc/config.py:203
#: src/rougail/output_doc/config.py:194
msgid "This file contains child variables of the family"
msgstr ""
#: src/rougail/output_doc/config.py:207
#: src/rougail/output_doc/config.py:198
msgid "Name of the file"
msgstr ""
#: src/rougail/output_doc/config.py:215
#: src/rougail/output_doc/config.py:206
msgid "Variables and changelog documentation"
msgstr ""
#: src/rougail/output_doc/config.py:220
#: src/rougail/output_doc/config.py:211
msgid "if \"_.output_format\" is json or \"_.contents\" hasn't variables or changelog"
msgstr ""
#: src/rougail/output_doc/config.py:223
#: src/rougail/output_doc/config.py:214
msgid "Do not add families in documentation"
msgstr ""
#: src/rougail/output_doc/config.py:228
#: src/rougail/output_doc/config.py:219
msgid "Add command line informations in documentation"
msgstr ""
#: src/rougail/output_doc/config.py:233
#: src/rougail/output_doc/config.py:224
msgid "Add environment variable informations in documentation"
msgstr ""
#: src/rougail/output_doc/config.py:238
#: src/rougail/output_doc/config.py:229
msgid "Environment variables prefix name"
msgstr ""
#: src/rougail/output_doc/config.py:245
#: src/rougail/output_doc/config.py:236
msgid "should only use uppercase characters"
msgstr ""
#: src/rougail/output_doc/config.py:250
#: src/rougail/output_doc/config.py:241
msgid "if \"main_namespace\" is not set or \"_.with_environment\" is false"
msgstr ""
#: src/rougail/output_doc/config.py:253
#: src/rougail/output_doc/config.py:244
msgid "Changelog documentation"
msgstr ""
#: src/rougail/output_doc/config.py:258
#: src/rougail/output_doc/config.py:249
msgid "if changelog in not in \"_.contents\""
msgstr ""
#: src/rougail/output_doc/config.py:261
#: src/rougail/output_doc/config.py:252
msgid "Previous description file in JSON format"
msgstr ""
#: src/rougail/output_doc/config.py:262
#: src/rougail/output_doc/config.py:253
msgid "To generate the changelog, you need to compare the old list of variables (in json format) with the current variables."
msgstr ""
#: src/rougail/output_doc/config.py:266
#: src/rougail/output_doc/config.py:257
msgid "Examples configuration"
msgstr ""
#: src/rougail/output_doc/config.py:271
#: src/rougail/output_doc/config.py:262
msgid "if example is not in \"_.contents\""
msgstr ""
#: src/rougail/output_doc/config.py:274
#: src/rougail/output_doc/config.py:265
msgid "Add description of variables and families when generate examples"
msgstr ""
#: src/rougail/output_doc/config.py:279
#: src/rougail/output_doc/config.py:270
msgid "Comment in examples starts at column"
msgstr ""
#: src/rougail/output_doc/doc.py:329
#: src/rougail/output_doc/doc.py:354
msgid "This family contains lists of variable blocks"
msgstr ""
#: src/rougail/output_doc/doc.py:339
#: src/rougail/output_doc/doc.py:364
msgid "This family builds families dynamically"
msgstr ""
#: src/rougail/output_doc/doc.py:353
#: src/rougail/output_doc/doc.py:378
msgid "Default"
msgstr ""
#: src/rougail/output_doc/doc.py:371
#: src/rougail/output_doc/doc.py:396
msgid "Example"
msgstr ""
#: src/rougail/output_doc/doc.py:374
#: src/rougail/output_doc/doc.py:399
msgid "Examples"
msgstr ""
#: src/rougail/output_doc/doc.py:383
#: src/rougail/output_doc/doc.py:408
msgid "Tag"
msgstr ""
#: src/rougail/output_doc/doc.py:386
#: src/rougail/output_doc/doc.py:411
msgid "Tags"
msgstr ""
#: src/rougail/output_doc/doc.py:418
#: src/rougail/output_doc/doc.py:443
msgid "No attribute \"description\" for \"{0}\" in {1}"
msgstr ""
#: src/rougail/output_doc/doc.py:553
#: src/rougail/output_doc/doc.py:578
msgid "text based with regular expressions \"{0}\""
msgstr ""
#: src/rougail/output_doc/doc.py:557
#: src/rougail/output_doc/doc.py:582
#: src/rougail/output_doc/tabular/six_columns.py:65
msgid "Validator"
msgstr ""
#: src/rougail/output_doc/doc.py:560
#: src/rougail/output_doc/doc.py:585
msgid "Validators"
msgstr ""
#: src/rougail/output_doc/doc.py:569
#: src/rougail/output_doc/doc.py:594
msgid "Choices"
msgstr ""
#: src/rougail/output_doc/doc.py:672
#: src/rougail/output_doc/doc.py:697
msgid "the value of the identifier"
msgstr ""
#: src/rougail/output_doc/doc.py:676
#: src/rougail/output_doc/doc.py:701
msgid "the value of the {0}"
msgstr ""
#: src/rougail/output_doc/doc.py:685
#: src/rougail/output_doc/doc.py:710
msgid "depends on a calculation"
msgstr ""
#: src/rougail/output_doc/doc.py:691
#: src/rougail/output_doc/doc.py:716
msgid "\"{0}\" is a calculation for {1} but has no description in {2}"
msgstr ""
#: src/rougail/output_doc/doc.py:719
#: src/rougail/output_doc/doc.py:744
msgid "the value of the variable \"{0}\""
msgstr ""
#: src/rougail/output_doc/doc.py:721
#: src/rougail/output_doc/doc.py:746
msgid "the value of the variable \"{0}\" if it is defined"
msgstr ""
#: src/rougail/output_doc/doc.py:741
#: src/rougail/output_doc/doc.py:766
msgid "the value of an undocumented variable"
msgstr ""
#: src/rougail/output_doc/doc.py:744
#: src/rougail/output_doc/doc.py:769
msgid "the values of undocumented variables"
msgstr ""
#: src/rougail/output_doc/doc.py:767
#: src/rougail/output_doc/doc.py:792
msgid "(from an undocumented variable)"
msgstr ""
#: src/rougail/output_doc/doc.py:775
#: src/rougail/output_doc/doc.py:800
msgid "{0} (from an undocumented variable)"
msgstr ""
#: src/rougail/output_doc/doc.py:779 src/rougail/output_doc/doc.py:831
#: src/rougail/output_doc/doc.py:804 src/rougail/output_doc/doc.py:856
msgid "depends on an undocumented variable"
msgstr ""
#: src/rougail/output_doc/doc.py:853
#: src/rougail/output_doc/doc.py:878
msgid "when the variable \"{{0}}\" is defined, accessible and hasn't the value \"{0}\""
msgstr ""
#: src/rougail/output_doc/doc.py:857
#: src/rougail/output_doc/doc.py:882
msgid "when the variable \"{{0}}\" is defined and hasn't the value \"{0}\""
msgstr ""
#: src/rougail/output_doc/doc.py:861
#: src/rougail/output_doc/doc.py:886
msgid "when the variable \"{{0}}\" is accessible and hasn't the value \"{0}\""
msgstr ""
#: src/rougail/output_doc/doc.py:863
#: src/rougail/output_doc/doc.py:888
msgid "when the variable \"{{0}}\" hasn't the value \"{0}\""
msgstr ""
#: src/rougail/output_doc/doc.py:867
#: src/rougail/output_doc/doc.py:892
msgid "when the variable \"{{0}}\" is defined, is accessible and has the value \"{0}\""
msgstr ""
#: src/rougail/output_doc/doc.py:871
#: src/rougail/output_doc/doc.py:896
msgid "when the variable \"{{0}}\" is defined and has the value \"{0}\""
msgstr ""
#: src/rougail/output_doc/doc.py:875
#: src/rougail/output_doc/doc.py:900
msgid "when the variable \"{{0}}\" is accessible and has the value \"{0}\""
msgstr ""
#: src/rougail/output_doc/doc.py:877
#: src/rougail/output_doc/doc.py:902
msgid "when the variable \"{{0}}\" has the value \"{0}\""
msgstr ""
#: src/rougail/output_doc/example.py:45
#: src/rougail/output_doc/example.py:62
msgid "Example with mandatory variables not filled in"
msgstr ""
#: src/rougail/output_doc/example.py:52
#: src/rougail/output_doc/example.py:69
msgid "Example with all variables modifiable"
msgstr ""
@ -378,21 +370,21 @@ msgstr ""
msgid "Environment variable"
msgstr ""
#: src/rougail/output_doc/utils.py:458
#: src/rougail/output_doc/utils.py:437
msgid "Path"
msgstr ""
#: src/rougail/output_doc/utils.py:468
#: src/rougail/output_doc/utils.py:447
msgid "Identifiers"
msgstr ""
#: src/rougail/output_doc/utils.py:684 src/rougail/output_doc/utils.py:693
#: src/rougail/output_doc/utils.py:699 src/rougail/output_doc/utils.py:705
#: src/rougail/output_doc/utils.py:709
#: src/rougail/output_doc/utils.py:663 src/rougail/output_doc/utils.py:672
#: src/rougail/output_doc/utils.py:678 src/rougail/output_doc/utils.py:684
#: src/rougail/output_doc/utils.py:688
msgid "(default)"
msgstr ""
#: src/rougail/output_doc/utils.py:960
#: src/rougail/output_doc/utils.py:940
msgid "{0}: {1}"
msgstr ""

2
src/rougail/output_doc/__init__.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/annotator.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
distribued with GPL-2 or later license

14
src/rougail/output_doc/changelog.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2025
Copyright (C) 2025-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the
@ -36,17 +36,7 @@ class Changelog: # pylint: disable=no-member,too-few-public-methods
self._added_variables = []
self._modified_variables = []
self._removed_variables = []
root = self.rougailconfig["doc.root"]
if root:
informations = self.informations
for family in root.split('.'):
informations = informations[family]["children"]
if previous_doc and family in previous_doc:
previous_doc = previous_doc[family]['children']
else:
previous_doc = {}
else:
informations = self.informations
informations = self.informations
self.formatter.options()
self.parser(previous_doc, informations)
return self.display()

11
src/rougail/output_doc/config.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the
@ -185,19 +185,10 @@ doc:
variable: _.output_format
when_not: console
root:
description: {_('Document the child variables of the family')}
help: {_('By default, all accessible variables are included in the documentation. It is possible to define the family from which the documentation should be generated.')}
alternative_name: dr
mandatory: false
other_root_filenames:
description: {_("The variables in this family are documented in another file")}
help: {_("If you separate the variables into different files, the links between the variables will break. Therefore, you must define different filenames for the files containing these variables.")}
type: leadership
disabled:
variable: _.root
when: null
root_path:
description: {_("This file contains child variables of the family")}

57
src/rougail/output_doc/doc.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the
@ -17,7 +17,7 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
from warnings import warn
from typing import Optional
from typing import Optional, Union
from itertools import chain
from re import compile
@ -47,9 +47,10 @@ class RougailOutputDoc(Examples, Changelog):
def __init__(
self,
config: "Config",
config: Union["Config", "SubConfig"],
*,
rougailconfig: "RougailConfig" = None,
true_config: "Config" = None,
**kwargs,
):
# Import here to avoid circular import
@ -66,6 +67,10 @@ class RougailOutputDoc(Examples, Changelog):
raise Exception("doc is not set as step.output")
self.outputs = OutPuts().get()
self.conf = config
if true_config is None:
self.true_config = config
else:
self.true_config = true_config
self.modes_level = rougailconfig["modes_level"]
self.disabled_modes = []
if self.modes_level:
@ -117,8 +122,30 @@ class RougailOutputDoc(Examples, Changelog):
informations = self.parse_families(config)
if informations is None:
informations = {}
elif self.conf.type() not in ['config', 'metaconfig', 'groupconfig', 'mixconfig']:
root_informations = {}
infos = root_informations
family = self.true_config
for path in self.conf.path().split('.'):
family = family.option(path)
name = family.name(uncalculated=True)
infos[name] = self.get_root_family(family)
infos = infos[name]["children"]
infos.update(informations)
informations = root_informations
self.informations = informations
def get_root_family(self, family):
family_informations = self._populate_family(
family,
)
if family_informations is not False:
return {
"type": self._get_family_type(family),
"informations": family_informations,
"children": {},
}
def populate_dynamics(self, *, config=None, reload=False):
if config is None:
config = self.conf.unrestraint
@ -194,7 +221,7 @@ class RougailOutputDoc(Examples, Changelog):
calculation = child.information.get(f"{hidden_property}_calculation", None)
if calculation and calculation.get("type") == "variable":
variable_path, value, condition = calculation["value"]
variable = self.conf.forcepermissive.option(variable_path)
variable = self.true_config.forcepermissive.option(variable_path)
try:
variable.value.get()
except AttributeError:
@ -214,17 +241,15 @@ class RougailOutputDoc(Examples, Changelog):
return False
def parse_family(self, family, informations: dict, *, force_injection=False) -> None:
path = family.path(uncalculated=True)
name = family.name(uncalculated=True)
sub_informations = self.parse_families(family)
if not force_injection and not sub_informations:
return
# if self.with_family:
family_informations = self._populate_family(
family,
path,
)
if family_informations is not False:
name = family.name(uncalculated=True)
informations[name] = {
"type": self._get_family_type(family),
"informations": family_informations,
@ -316,8 +341,8 @@ class RougailOutputDoc(Examples, Changelog):
def _populate_family(
self,
family,
path: str,
) -> dict:
path = family.path(uncalculated=True)
if family.isdynamic():
informations = self.dynamic_paths[path]
else:
@ -712,7 +737,7 @@ class RougailOutputDoc(Examples, Changelog):
return None
else:
try:
self.conf.forcepermissive.option(path).get()
self.true_config.forcepermissive.option(path).get()
except AttributeError:
return None
if not calculation["optional"]:
@ -747,7 +772,7 @@ class RougailOutputDoc(Examples, Changelog):
else:
# FIXME A MUTUALISER AUSSI
variable_path = calculation["ori_path"]
variable = self.conf.unrestraint.option(variable_path)
variable = self.true_config.unrestraint.option(variable_path)
try:
isfollower = variable.isfollower()
except AttributeError:
@ -782,7 +807,7 @@ class RougailOutputDoc(Examples, Changelog):
values = true_msg
else:
try:
description = self._convert_description(self.conf.option(calculation["ori_path"]).description(uncalculated=True), "description", its_a_path=False)
description = self._convert_description(self.true_config.option(calculation["ori_path"]).description(uncalculated=True), "description", its_a_path=False)
except AttributeError:
description = calculation["ori_path"]
values = {
@ -806,7 +831,7 @@ class RougailOutputDoc(Examples, Changelog):
if "{{ identifier }}" in calculation["ori_path"] or "{{ identifier }}" in variable_path:
variables = self.get_annotation_variable(variable_path, calculation["ori_path"])
else:
option = self.conf.option(variable_path)
option = self.true_config.option(variable_path)
try:
is_inaccessible = self.is_inaccessible_user_data(option)
except AttributeError as err:
@ -820,7 +845,7 @@ class RougailOutputDoc(Examples, Changelog):
variables = [[variable_path, description, None]]
for cpath, description, identifiers in variables:
if not cpath:
variable = self.conf.forcepermissive.option(variable_path)
variable = self.true_config.forcepermissive.option(variable_path)
try:
variable_value = self._get_unmodified_default_value(variable)
except PropertiesOptionError as err:
@ -905,10 +930,10 @@ class RougailOutputDoc(Examples, Changelog):
cpath = calc_path(path, identifiers=identifiers)
if regexp and not regexp.search(cpath):
continue
if self.is_inaccessible_user_data(self.conf.option(cpath)):
if self.is_inaccessible_user_data(self.true_config.option(cpath)):
yield None, None, None
else:
description = self._convert_description(self.conf.option(path).description(uncalculated=True), "description", its_a_path=False)
description = self._convert_description(self.true_config.option(path).description(uncalculated=True), "description", its_a_path=False)
if "{{ identifier }}" in path:
yield path, description, identifiers.copy()
else:
@ -919,7 +944,7 @@ class RougailOutputDoc(Examples, Changelog):
if not calculation:
return child.value.get()
if calculation["type"] == "variable":
variable = self.conf.forcepermissive.option(calculation["value"])
variable = self.true_config.forcepermissive.option(calculation["value"])
if variable and self.is_inaccessible_user_data(variable):
return self._get_unmodified_default_value(variable)
raise VariableCalculationDependencyError()

45
src/rougail/output_doc/example.py
View file

@ -1,7 +1,7 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
@ -18,10 +18,28 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
from typing import Optional
from ruamel.yaml import CommentedMap
from ruamel.yaml.representer import RoundTripRepresenter
from .utils import _, calc_path
# XXX explicit null (see rougail-output-formatter
def represent_none(self, data):
return self.represent_scalar("tag:yaml.org,2002:null", "null")
def represent_str(self, data):
if data == "":
return self.represent_scalar("tag:yaml.org,2002:null", "")
return self.represent_scalar("tag:yaml.org,2002:str", data)
RoundTripRepresenter.add_representer(type(None), represent_none)
RoundTripRepresenter.add_representer(str, represent_str)
# XXX
class Examples: # pylint: disable=no-member,too-few-public-methods
"""Build examples"""
@ -31,12 +49,11 @@ class Examples: # pylint: disable=no-member,too-few-public-methods
def gen_doc_examples(self):
"""Return examples"""
root = self.rougailconfig["doc.root"]
self.comment_examples = self.rougailconfig["doc.examples.comment"]
self.level = self.rougailconfig["doc.title_level"]
if self.comment_examples:
self.comment_examples_column = self.rougailconfig["doc.examples.comment_column"]
self._build_examples(root)
self._build_examples()
return_string = ""
datas = []
if self.examples_mandatories:
@ -56,28 +73,10 @@ class Examples: # pylint: disable=no-member,too-few-public-methods
])
return self.formatter.compute(datas)
def _build_examples(self, root):
def _build_examples(self):
examples, examples_mandatories = self._parse_examples(
self.informations
)
if root and examples:
sub_examples = examples
sub_examples_mandatories = examples_mandatories
new_examples_mandatories = examples_mandatories = {}
new_examples = examples = {}
for sub in root.split('.'):
new_examples[sub] = {}
new_examples = new_examples[sub]
sub_examples = sub_examples[sub]
if examples_mandatories and sub in sub_examples_mandatories:
new_examples_mandatories[sub] = {}
new_examples_mandatories = new_examples_mandatories[sub]
sub_examples_mandatories = sub_examples_mandatories[sub]
else:
new_examples_mandatories = {}
sub_examples_mandatories = {}
new_examples.update(sub_examples)
new_examples_mandatories.update(sub_examples_mandatories)
self.examples = examples
self.examples_mandatories = examples_mandatories

2
src/rougail/output_doc/i18n.py
View file

@ -1,6 +1,6 @@
"""Internationalisation utilities
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

BIN
src/rougail/output_doc/locale/fr/LC_MESSAGES/rougail_output_doc.mo
View file

Binary file not shown.

2
src/rougail/output_doc/output/__init__.py
View file

@ -1,6 +1,6 @@
"""Loads output
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/output/asciidoc.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/output/console.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/output/github.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/output/gitlab.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2025
Copyright (C) 2025-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/output/html.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2025
Copyright (C) 2025-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

13
src/rougail/output_doc/output/ojson.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the
@ -31,10 +31,9 @@ class Formatter:
def run(self, informations: dict, *args) -> str: # pylint: disable=unused-argument
"""Transform to string"""
root = self.rougailconfig["doc.root"]
if root:
current = informations
for path in root.split('.'):
current = current[path]["children"]
informations = current
# if root:
# current = informations
# for path in root.split('.'):
# current = current[path]["children"]
# informations = current
return dumps(informations, ensure_ascii=False, indent=2)

2
src/rougail/output_doc/tabular/__init__.py
View file

@ -1,6 +1,6 @@
"""Loads output
Silique (https://www.silique.fr)
Copyright (C) 2025
Copyright (C) 2025-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/tabular/five_columns.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2025
Copyright (C) 2025-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/tabular/four_columns.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2025
Copyright (C) 2025-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/tabular/six_columns.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2025
Copyright (C) 2025-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/tabular/three_columns.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2025
Copyright (C) 2025-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

2
src/rougail/output_doc/tabular/two_columns.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2025
Copyright (C) 2025-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the

25
src/rougail/output_doc/utils.py
View file

@ -1,6 +1,6 @@
"""
Silique (https://www.silique.fr)
Copyright (C) 2024-2025
Copyright (C) 2024-2026
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the
@ -201,12 +201,6 @@ class CommonFormatter:
if informations:
level = self.rougailconfig["doc.title_level"]
self.options()
if self.root:
current = informations
for path in self.root.split('.'):
info = current[path]['informations']
current = current[path]["children"]
informations = {"informations": info, "children": current}
return self._run(informations, level, dico_is_already_treated)
return ""
@ -221,16 +215,7 @@ class CommonFormatter:
else:
self.prefix = self.rougailconfig["doc.tabulars.environment_prefix"] + "_"
self.with_family = not self.rougailconfig["doc.tabulars.without_family"]
self.root = self.rougailconfig["doc.root"]
self.other_root_filenames = None
if self.root:
try:
other_root_filenames = self.rougailconfig["doc.other_root_filenames"]
except PropertiesOptionError:
pass
else:
if other_root_filenames:
self.other_root_filenames = dict(zip(other_root_filenames["root_path"], other_root_filenames["filename"]))
tabular_template = self.rougailconfig["doc.tabular_template"]
self.tabular_datas = Tabulars().get()[tabular_template](self)
@ -406,11 +391,6 @@ class CommonFormatter:
) -> str:
"""Parse the dict to transform to dict"""
msg = []
if init and self.root:
if self.with_family:
msg.extend(self.family_to_string(dico["informations"], level, False))
level += 1
dico = dico["children"]
for value in dico.values():
if value["type"] == "variable":
self.variable_to_string(value)
@ -446,7 +426,6 @@ class CommonFormatter:
ret = [self.namespace_to_title(informations, level)]
else:
ret = [self.title(self.get_description("family", informations, {}, None), level)]
# ret.append(self.anchor("", informations["path"]) + ENTER)
fam_info = self.family_informations()
if fam_info:
ret.append(fam_info)
@ -824,7 +803,6 @@ class CommonFormatter:
or new[prop_name] != previous[prop_name]
):
underline_ = True
# prop_annotation = self.underline(prop_annotation)
else:
underline_ = False
local_calculated_properties.setdefault(prop["name"], []).append(
@ -838,7 +816,6 @@ class CommonFormatter:
calculated_property_name,
calculated_property,
) in local_calculated_properties.items():
# calculated_property = calculated_property_data["annotation"]
data = []
for calc in calculated_property:
annotation = self.message_to_string(calc["annotation"], None)[1]

60
tests/cmdline/00_file.yml
View file

@ -1,60 +0,0 @@
---
version: 1.1
var1:
description: my var1
alternative_name: v
var2:
description: my var2
default:
jinja: |
{{ a.unknown.variable }}
description: var calculated
var3:
description: my var3
hidden:
jinja: |
{% if a.unknown.variable == 'value' %}
it's hidden
{% endif %}
description: var could be hidden
var4:
description: my var4
hidden:
variable: a.unknown.variable
when: 'value'
var5:
description: my var5
default:
type: information
information: info
variable: a.unknown.variable
var6:
description: my var6
choices:
variable: a.unknown.variable
var7:
description: my var7
choices:
- variable: a.unknown.variable1
- variable: a.unknown.variable2
var8:
description: my var8
choices:
jinja: |
a.unknown.variable
description: the a.unknown.variable values
"var{{ identifier }}":
description: my var6
dynamic:
variable: a.unknown.variable
var:
description: a variable

9
tests/root_a_family.an_other_family.adoc
View file

@ -1,4 +1,11 @@
== An other family
== First family
====
**🛈 Informations**
**Path**: a_family
====
=== An other family
====
**🛈 Informations**

9
tests/root_a_family.an_other_family.gitlab.md
View file

@ -1,3 +1,8 @@
<details><summary>First family</summary>
> [!note] 🛈 Informations
> **Path**: a_family
<details><summary>An other family</summary>
> [!note] 🛈 Informations
@ -9,3 +14,7 @@
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| **<a id="a_family.an_other_family.a_variable" name="a_family.an_other_family.a_variable">a_family.an_other_family.a_variable</a>**<br/>[`integer`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | A new variable.<br/>**Default**: the value of the variable "[A root variable](#a_variable)" |
</details>
</details>

6
tests/root_a_family.an_other_family.html
View file

@ -1,4 +1,8 @@
<h1>An other family</h1>
<h1>First family</h1>
<b>Path</b>: a_family
<h2>An other family</h2>
<b>Path</b>: a_family.an_other_family

96
tests/root_a_family.an_other_family.json
View file

@ -1,33 +1,73 @@
{
"a_variable": {
"type": "variable",
"default": {
"name": "Default",
"values": {
"message": "the value of the variable \"{0}\"",
"path": {
"path": "a_variable"
},
"description": "A root variable"
}
"a_family": {
"type": "family",
"informations": {
"path": "a_family",
"names": [
"a_family"
],
"description": "First family",
"properties": []
},
"variable_type": "integer",
"path": "a_family.an_other_family.a_variable",
"names": [
"a_variable"
],
"description": "A new variable.",
"properties": [
{
"type": "property",
"name": "mandatory",
"ori_name": "mandatory",
"access_control": false
"children": {
"an_other_family": {
"type": "family",
"informations": {
"path": "a_family.an_other_family",
"names": [
"an_other_family"
],
"description": "An other family",
"properties": [
{
"type": "property",
"name": "hidden",
"ori_name": "hidden",
"access_control": true,
"annotation": {
"message": "when the variable \"{0}\" has the value \"true\"",
"path": {
"path": "a_family.a_second_family.a_variable"
},
"description": "A boolean variable"
}
}
]
},
"children": {
"a_variable": {
"type": "variable",
"default": {
"name": "Default",
"values": {
"message": "the value of the variable \"{0}\"",
"path": {
"path": "a_variable"
},
"description": "A root variable"
}
},
"variable_type": "integer",
"path": "a_family.an_other_family.a_variable",
"names": [
"a_variable"
],
"description": "A new variable.",
"properties": [
{
"type": "property",
"name": "mandatory",
"ori_name": "mandatory",
"access_control": false
}
],
"gen_examples": [
2
],
"mandatory_without_value": false
}
}
}
],
"gen_examples": [
2
],
"mandatory_without_value": false
}
}
}

8
tests/root_a_family.an_other_family.md
View file

@ -1,4 +1,10 @@
# An other family
# First family
> [!NOTE]
>
> **Path**: a_family
## An other family
> [!NOTE]
>

10
tests/root_a_family.an_other_family.sh
View file

@ -1,4 +1,10 @@
An other family
First family
▌ 🛈 Informations
▌ 
▌ Path: a_family
An other family
▌ 🛈 Informations
▌ 
@ -14,3 +20,5 @@
│  integer   mandatory  │ Default: the value of the variable │
│ │ "a_variable" │
└───────────────────────────────────────┴──────────────────────────────────────┘

2
tests/root_a_family.gitlab.md
View file

@ -27,3 +27,5 @@
</details>
</details>

173
tests/root_a_family.json
View file

@ -1,97 +1,110 @@
{
"a_second_family": {
"a_family": {
"type": "family",
"informations": {
"path": "a_family.a_second_family",
"path": "a_family",
"names": [
"a_second_family"
"a_family"
],
"description": "A second family",
"description": "First family",
"properties": []
},
"children": {
"a_variable": {
"type": "variable",
"default": {
"name": "Default",
"values": true
"a_second_family": {
"type": "family",
"informations": {
"path": "a_family.a_second_family",
"names": [
"a_second_family"
],
"description": "A second family",
"properties": []
},
"variable_type": "boolean",
"path": "a_family.a_second_family.a_variable",
"names": [
"a_variable"
],
"description": "A boolean variable.",
"properties": [
{
"type": "property",
"name": "mandatory",
"ori_name": "mandatory",
"access_control": false
}
],
"gen_examples": [
true
],
"mandatory_without_value": false
}
}
},
"an_other_family": {
"type": "family",
"informations": {
"path": "a_family.an_other_family",
"names": [
"an_other_family"
],
"description": "An other family",
"properties": [
{
"type": "property",
"name": "hidden",
"ori_name": "hidden",
"access_control": true,
"annotation": {
"message": "when the variable \"{0}\" has the value \"true\"",
"path": {
"path": "a_family.a_second_family.a_variable"
"children": {
"a_variable": {
"type": "variable",
"default": {
"name": "Default",
"values": true
},
"description": "A boolean variable"
"variable_type": "boolean",
"path": "a_family.a_second_family.a_variable",
"names": [
"a_variable"
],
"description": "A boolean variable.",
"properties": [
{
"type": "property",
"name": "mandatory",
"ori_name": "mandatory",
"access_control": false
}
],
"gen_examples": [
true
],
"mandatory_without_value": false
}
}
]
},
"children": {
"a_variable": {
"type": "variable",
"default": {
"name": "Default",
"values": {
"message": "the value of the variable \"{0}\"",
"path": {
"path": "a_variable"
},
"description": "A root variable"
}
},
"an_other_family": {
"type": "family",
"informations": {
"path": "a_family.an_other_family",
"names": [
"an_other_family"
],
"description": "An other family",
"properties": [
{
"type": "property",
"name": "hidden",
"ori_name": "hidden",
"access_control": true,
"annotation": {
"message": "when the variable \"{0}\" has the value \"true\"",
"path": {
"path": "a_family.a_second_family.a_variable"
},
"description": "A boolean variable"
}
}
]
},
"variable_type": "integer",
"path": "a_family.an_other_family.a_variable",
"names": [
"a_variable"
],
"description": "A new variable.",
"properties": [
{
"type": "property",
"name": "mandatory",
"ori_name": "mandatory",
"access_control": false
"children": {
"a_variable": {
"type": "variable",
"default": {
"name": "Default",
"values": {
"message": "the value of the variable \"{0}\"",
"path": {
"path": "a_variable"
},
"description": "A root variable"
}
},
"variable_type": "integer",
"path": "a_family.an_other_family.a_variable",
"names": [
"a_variable"
],
"description": "A new variable.",
"properties": [
{
"type": "property",
"name": "mandatory",
"ori_name": "mandatory",
"access_control": false
}
],
"gen_examples": [
2
],
"mandatory_without_value": false
}
],
"gen_examples": [
2
],
"mandatory_without_value": false
}
}
}
}

1
tests/root_a_family.sh
View file

@ -34,3 +34,4 @@
│ │ "a_variable" │
└───────────────────────────────────────┴──────────────────────────────────────┘

27
tests/test_cmdline.py
View file

@ -1,27 +0,0 @@
from pathlib import Path
from rougail import Rougail
from rougail.config import get_rougail_config
from rougail.output_doc import RougailOutputDoc
def test_force_optional():
print('FIXME')
# test_dir = Path(__file__).resolve().parent
# rougailconfig = get_rougail_config(backward_compatibility=False)
# rougailconfig['step.output'] = 'doc'
## rougailconfig['tiramisu_cache'] = 'p.py'
# dirs = [str(test_dir / 'cmdline')]
# rougailconfig['plugins'] = ["structural_commandline"]
# rougailconfig['main_structural_directories'] = dirs
# rougailconfig['doc.output_format'] = 'asciidoc'
# rougail = Rougail(rougailconfig)
# config = rougail.run()
# inventory = RougailOutputDoc(config, rougailconfig=rougailconfig)
# doc = inventory.run()
# result_file = test_dir / 'cmdline.adoc'
# if not result_file.is_file():
# with open(str(result_file), 'w') as docfh:
# docfh.write(doc)
# with open(str(result_file)) as docfh:
# result = docfh.read()
# assert doc == result

5
tests/test_root.py
View file

@ -20,14 +20,15 @@ def _test_root(root, contents=None):
rougailconfig['main_structural_directories'] = dirs
rougail = Rougail(rougailconfig)
config = rougail.run()
rougailconfig['doc.root'] = root
subconfig = config.option(root)
# rougailconfig['doc.root'] = root
if contents == 'changelog':
rougailconfig["doc.changelog.previous_json_file"] = str(test_dir / "empty/out.json")
for output_format, ext in EXT.items():
if output_format == 'json' and contents:
continue
rougailconfig['doc.output_format'] = output_format
inventory = RougailOutputDoc(config, rougailconfig=rougailconfig)
inventory = RougailOutputDoc(subconfig, rougailconfig=rougailconfig, true_config=config)
doc = inventory.run()[1]
if contents:
result_file = test_dir / f'root_{root}_{contents}.{ext}'