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
doc.output_format choice mandatory Command line: -do, –doc.output_format Environment variable: ROUGAILCLI_DOC.OUTPUT_FORMAT	The output format of the generated documentation. Choices: console ← (default) asciidoc html github gitlab restructuredtext json
doc.tabular_template choice mandatory *disabled* Command line: -dm, –doc.tabular_template Environment variable: ROUGAILCLI_DOC.TABULAR_TEMPLATE	Generate document with this tabular model. The variables are documented with a tabular view. A template selection allows you to choose the content of each column. Choices: two_columns ← (default) three_columns four_columns five_columns six_columns Disabled: “the output format of the generated documentation” (doc.output_format) in json is not compatible with this variable.
doc.contents choice multiple mandatory *hidden* unique Command line: -dc, –doc.contents Environment variable: ROUGAILCLI_DOC.CONTENTS	Generated content. You can generate three type of document. All variables (“variables”), an example file in YAML format (“example”) or change log (“changelog”). Choices: variables ← (default) example changelog Hidden: “the output format of the generated documentation” (doc.output_format) in json is not compatible with changelog or example “generated content” (doc.contents).
doc.title_level integer mandatory Command line: -dt, –doc.title_level Environment variable: ROUGAILCLI_DOC.TITLE_LEVEL	Starting title level. Default: 1
doc.default_values boolean mandatory Command line: –doc.default_values –doc.no-default_values Environment variable: ROUGAILCLI_DOC.DEFAULT_VALUES	Modify values to document all variables. 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. Default: true
doc.true_color boolean mandatory *disabled* Command line: –doc.true_color –doc.no-true_color Environment variable: ROUGAILCLI_DOC.TRUE_COLOR	Display documentation in console always with true color terminal. Default: false 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
doc.other_root_filenames.root_path string multiple unique Command line: –doc.other_root_filenames.root_path Environment variable: ROUGAILCLI_DOC.OTHER_ROOT_FILENAMES.ROOT_PATH	This file contains child variables of the family.
doc.other_root_filenames.root_doc_path string Command line: –doc.other_root_filenames.root_doc_path Environment variable: ROUGAILCLI_DOC.OTHER_ROOT_FILENAMES.ROOT_DOC_PATH	Name of the file.

Variable	Description
doc.document_a_type boolean mandatory Command line: –doc.document_a_type –doc.no-document_a_type Environment variable: ROUGAILCLI_DOC.DOCUMENT_A_TYPE	Documentation a structural type. Default: false

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
doc.tabulars.without_family boolean mandatory Command line: -df, –doc.tabulars.without_family -ndf, –doc.tabulars.no-without_family Environment variable: ROUGAILCLI_DOC.TABULARS.WITHOUT_FAMILY	Do not add families in documentation. Default: false
doc.tabulars.with_commandline boolean mandatory Environment variable: ROUGAILCLI_DOC.TABULARS.WITH_COMMANDLINE	Add command line informations in documentation. Default: false
doc.tabulars.with_environment boolean mandatory Command line: -de, –doc.tabulars.with_environment -nde, –doc.tabulars.no-with_environment Environment variable: ROUGAILCLI_DOC.TABULARS.WITH_ENVIRONMENT	Add environment variable informations in documentation. Default: false
doc.tabulars.environment_prefix string *disabled* Command line: -dv, –doc.tabulars.environment_prefix Environment variable: ROUGAILCLI_DOC.TABULARS.ENVIRONMENT_PREFIX	Environment variables prefix name. Validator: should only use uppercase characters Default: ROUGAIL Disabled: when the variable “add environment variable informations in documentation” (doc.tabulars.with_environment) has the value “false”.

Changelog documentation

Note

Path: doc.changelog

*disabled*

Disabled: if changelog in not in “generated content” (doc.contents).

Variable	Description
doc.changelog.previous_json_file string mandatory Command line: -dp, –doc.changelog.previous_json_file Environment variable: ROUGAILCLI_DOC.CHANGELOG.PREVIOUS_JSON_FILE	Previous description file in JSON format. To generate the changelog, you need to compare the old list of variables (in json format) with the current variables.

Examples configuration

Note

Path: doc.examples

*disabled*

Disabled: if example is not in “generated content” (doc.contents).

Variable	Description
doc.examples.comment boolean mandatory Command line: -dx, –doc.examples.comment -ndx, –doc.examples.no-comment Environment variable: ROUGAILCLI_DOC.EXAMPLES.COMMENT	Add description of variables and families when generate examples. Default: false
doc.examples.comment_column integer mandatory *disabled* Command line: –doc.examples.comment_column Environment variable: ROUGAILCLI_DOC.EXAMPLES.COMMENT_COLUMN	Comment in examples starts at column. Default: 30 Disabled: when the variable “add description of variables and families when generate examples” (doc.examples.comment) has the value “false”.