81 lines
20 KiB
Markdown
81 lines
20 KiB
Markdown
---
|
|
gitea: none
|
|
include_toc: true
|
|
---
|
|
[🇬🇧 (EN)](README.md) - [🇫🇷 (FR)](README.fr.md)
|
|
|
|
## Generate documentation from structural files
|
|
|
|
> **🛈 Informations**
|
|
>
|
|
> 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 doc is not set in "[Select for output](#step.output)"
|
|
|
|
| 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**: ROUGAILCLI_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/>• console<br/>• asciidoc<br/>• html<br/>• github<br/>• gitlab<br/>• json |
|
|
| **<a id="doc.tabular_template" name="doc.tabular_template">doc.tabular_template</a>**<br/>**Command line**: -dm, --doc.tabular_template<br/>**Environment variable**: ROUGAILCLI_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/>• two_columns<br/>• three_columns<br/>• four_columns<br/>• five_columns<br/>• six_columns |
|
|
| **<a id="doc.contents" name="doc.contents">doc.contents</a>**<br/>**Command line**: -dc, --doc.contents<br/>**Environment variable**: ROUGAILCLI_DOC.CONTENTS | Generated content.<br/>You can generate three type of document. All variables ("variables"), an example file in YAML format ("example") or change log ("changelog"). | • 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/>• variables<br/>• example<br/>• changelog |
|
|
| **<a id="doc.title_level" name="doc.title_level">doc.title_level</a>**<br/>**Command line**: -dt, --doc.title_level<br/>**Environment variable**: ROUGAILCLI_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/>• --doc.default_values<br/>• --doc.no-default_values<br/>**Environment variable**: ROUGAILCLI_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/>• --doc.true_color<br/>• --doc.no-true_color<br/>**Environment variable**: ROUGAILCLI_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**: ROUGAILCLI_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
|
|
|
|
> **🛈 Informations**
|
|
>
|
|
> 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"
|
|
|
|
| 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**: ROUGAILCLI_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**: ROUGAILCLI_DOC.OTHER_ROOT_FILENAMES.FILENAME | Name of the file. | [`UNIX filename`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | • this filename could be a relative path<br/>• file type allowed: "file". |
|
|
|
|
### Variables and changelog documentation
|
|
|
|
> **🛈 Informations**
|
|
>
|
|
> **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/>• -df, --doc.tabulars.without_family<br/>• -ndf, --doc.tabulars.no-without_family<br/>**Environment variable**: ROUGAILCLI_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/>• -dw, --doc.tabulars.with_commandline<br/>• -ndw, --doc.tabulars.no-with_commandline<br/>**Environment variable**: ROUGAILCLI_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/>• -de, --doc.tabulars.with_environment<br/>• -nde, --doc.tabulars.no-with_environment<br/>**Environment variable**: ROUGAILCLI_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**: ROUGAILCLI_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
|
|
|
|
> **🛈 Informations**
|
|
>
|
|
> **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**: -dp, --doc.changelog.previous_json_file<br/>**Environment variable**: ROUGAILCLI_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
|
|
|
|
> **🛈 Informations**
|
|
>
|
|
> **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/>• -dx, --doc.examples.comment<br/>• -ndx, --doc.examples.no-comment<br/>**Environment variable**: ROUGAILCLI_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**: ROUGAILCLI_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" |
|
|
|
|
|