rougail/docs/output/doc.rst

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.



.. list-table::

   * - Variable
     - Description

   * - **doc.output_format**

       `choice <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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 <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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 <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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 <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `mandatory`

       **Command line**: 

       -dt, --doc.title_level

       **Environment variable**: ROUGAILCLI_DOC.TITLE_LEVEL
     - Starting title level.

       **Default**: 1

   * - **doc.default_values**

       `boolean <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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 <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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



.. list-table::

   * - Variable
     - Description

   * - **doc.other_root_filenames.root_path**

       `string <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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 <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__

       **Command line**: 

       --doc.other_root_filenames.root_doc_path

       **Environment variable**: ROUGAILCLI_DOC.OTHER_ROOT_FILENAMES.ROOT_DOC_PATH
     - Name of the file.



.. list-table::

   * - Variable
     - Description

   * - **doc.document_a_type**

       `boolean <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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.



.. list-table::

   * - Variable
     - Description

   * - **doc.tabulars.without_family**

       `boolean <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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 <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `mandatory`

       **Environment variable**: ROUGAILCLI_DOC.TABULARS.WITH_COMMANDLINE
     - Add command line informations in documentation.

       **Default**: false

   * - **doc.tabulars.with_environment**

       `boolean <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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 <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `*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).



.. list-table::

   * - Variable
     - Description

   * - **doc.changelog.previous_json_file**

       `string <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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).



.. list-table::

   * - Variable
     - Description

   * - **doc.examples.comment**

       `boolean <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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 <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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".