Metadata-Version: 2.4
Name: rougail.output_doc
Version: 1.0.1
Summary: Rougail output doc
Author-email: Emmanuel Garette <gnunux@gnunux.info>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Natural Language :: French
License-File: LICENSE
Requires-Dist: rougail-base >= 1.2.0,<2
Requires-Dist: tabulate ~= 0.10.0
Requires-Dist: rich ~= 13.9.3
Project-URL: Home, https://forge.cloud.silique.fr/stove/rougail-output-exporter

---
gitea: none
include_toc: true
---
[🇬🇧 (EN)](README.md) - [🇫🇷 (FR)](README.fr.md)

## Generate documentation from structural files

> [!NOTE]
> 
> The structural files contain all the information related to the variables. This output generates the documentation for all or some of these variables.\
> **Path**: doc\
> *`disabled`*\
> **Disabled**: if "[select for output](#step.output)" is not doc.

| Variable                                                                                                                                                                                                                   | Description                                                                                                                                                                                                                                  | Default value    | Type                                                                                                      | Access control                                                                                                                                                                                | Validator                                                                                                                            |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|-----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| **<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.                                         | **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)". | `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".                                         |                                                                                                                                      |

### The variables in this family are documented in another file

> [!NOTE]
> 
> 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

| 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.root_doc_path" name="doc.other_root_filenames.root_doc_path">doc.other_root_filenames.root_doc_path</a>**<br/>**Command line**: <br/>--doc.other_root_filenames.root_doc_path<br/>**Environment variable**: DOC.OTHER_ROOT_FILENAMES.ROOT_DOC_PATH | Name of the file.                                 | [`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types)            |             |

| Variable                                                                                                                                                                                                                         | Description                      | Default value   | Type                                                                                            |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|-----------------|-------------------------------------------------------------------------------------------------|
| **<a id="doc.document_a_type" name="doc.document_a_type">doc.document_a_type</a>**<br/>**Command line**: <br/>•&nbsp;--doc.document_a_type<br/>•&nbsp;--doc.no-document_a_type<br/>**Environment variable**: DOC.DOCUMENT_A_TYPE | Documentation a structural type. | false           | [`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` |

### Variables and changelog documentation

> [!NOTE]
> 
> **Path**: doc.tabulars\
> *`disabled`*\
> **Disabled**: if "[the output format of the generated documentation](#doc.output_format)" is json or "[generated content](#doc.contents)" hasn't variables or changelog.

| Variable                                                                                                                                                                                                                                                                                                | Description                                             | Default value   | Type                                                                                            | Access control                                                                                                                                                        | Validator                             |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|
| **<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/>**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**: <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

> [!NOTE]
> 
> **Path**: doc.changelog\
> *`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**: <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

> [!NOTE]
> 
> **Path**: doc.examples\
> *`disabled`*\
> **Disabled**: if example is not in "[generated content](#doc.contents)".

| 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**: <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". |

