Environment variable documentation helpers

Any environment variables that are loaded using maykin_common.config.config(), can be documented using the documentation helpers (unless add_to_docs is explicitly set to False). Documentation per environment variable can be added by providing the documentation parameter, which has the following attributes:

  • help_text: the description of the environment variable.

  • group: the name of the group to list this environment variable under (defaults to Required if no default is specified, otherwise Optional).

  • add_to_docs: whether or not this environment variable should be included in the docs (default True)

  • auto_display_default: whether or not the default specified to the config helper should be displayed in the documentation (default True)

from maykin_common.config_helpers import config, DocumentationParams

ALLOWED_HOSTS = config(
    "ALLOWED_HOSTS",
    default="",
    split=True,
    documentation=DocumentationParams(
        help_text=(
            "a comma separated (without spaces!) list of domains that serve "
            "the installation. Used to protect against Host header attacks."
        ),
        group="Required",
    )
)

To exclude an environment variable from the documentation, the following shorthand can be used:

from maykin_common.config_helpers import config, no_doc

VARIABLE_TO_BE_EXCLUDED = config(
    "VARIABLE_TO_BE_EXCLUDED",
    default="",
    documentation=no_doc
)

In order to document environment variables that are defined in this way, there are three Sphinx directives that can be used.

To document all groups of environment variables, the config-all-params directive (maykin_common.documentation.config_directives.ConfigAllParamsDirective) can be used. This directive accepts the following optional arguments:

  • members-groups to only use the specified groups

  • exclude-groups to exclude the specified groups (cannot be used together with members-groups)

  • exclude-params to exclude the specified environment variables

Example usage:

.. config-all-params::
    :exclude-groups: Celery, Database

To document a specific group of environment variables, the config-group directive (maykin_common.documentation.config_directives.ConfigGroupDirective) can be used. This directive accepts the following optional arguments:

  • members to only use the specified environment variables

  • exclude to exclude the specified environment variables (cannot be used together with members)

Example usage:

.. config-group:: Database
    :exclude: DB_POOL_MAX_LIFETIME, DB_POOL_NUM_WORKERS

To document a single environment variable, the config-param directive (maykin_common.documentation.config_directives.ConfigParamDirective) can be used. This directive accepts the following optional arguments:

  • default to override the default as defined in the code

.. config-param:: DISABLE_2FA
    :default: True