diff --git a/open_api_framework/conf/utils.py b/open_api_framework/conf/utils.py index 323fcf1..ed425a9 100644 --- a/open_api_framework/conf/utils.py +++ b/open_api_framework/conf/utils.py @@ -14,6 +14,7 @@ class EnvironmentVariable: default: Any help_text: str group: Optional[str] = None + sub_group: Optional[str] = None auto_display_default: bool = True def __post_init__(self): @@ -34,6 +35,7 @@ def config( default: Any = undefined, help_text="", group=None, + sub_group=None, add_to_docs=True, auto_display_default=True, *args, @@ -56,6 +58,7 @@ def config( :param help_text: The help text to be displayed for this variable in the documentation. Default `""` :param group: The name of the section under which this variable will be grouped. Default ``None`` + :param sub_group: The name of the subsection under which this variable will be grouped. Default ``None`` :param add_to_docs: Whether or not this variable will be displayed in the documentation. Default ``True`` :param auto_display_default: Whether or not the passed ``default`` value is displayed in the docs, this can be set to ``False`` in case a default needs more explanation that can be added to the ``help_text`` @@ -67,6 +70,7 @@ def config( default=default, help_text=help_text, group=group, + sub_group=sub_group, auto_display_default=auto_display_default, ) if variable not in ENVVAR_REGISTRY: diff --git a/open_api_framework/management/commands/generate_envvar_docs.py b/open_api_framework/management/commands/generate_envvar_docs.py index b31de3a..663102e 100644 --- a/open_api_framework/management/commands/generate_envvar_docs.py +++ b/open_api_framework/management/commands/generate_envvar_docs.py @@ -9,11 +9,11 @@ def convert_variables_to_rst(variables: list[EnvironmentVariable]) -> str: template = loader.get_template("open_api_framework/env_config.rst") - grouped_vars = defaultdict(list) + grouped_vars = defaultdict(lambda: defaultdict(list)) for var in variables: if not var.help_text: warnings.warn(f"missing help_text for environment variable {var}") - grouped_vars[var.group].append(var) + grouped_vars[var.group][var.sub_group].append(var) return template.render({"vars": grouped_vars.items()}) @@ -47,6 +47,8 @@ def _sort(envvar): return 0 case "Optional": return 2 + case "Setup Configuration": + return 3 case _: return 1 diff --git a/open_api_framework/templates/open_api_framework/env_config.rst b/open_api_framework/templates/open_api_framework/env_config.rst index 46b74b4..20e5ffc 100644 --- a/open_api_framework/templates/open_api_framework/env_config.rst +++ b/open_api_framework/templates/open_api_framework/env_config.rst @@ -9,11 +9,19 @@ Environment configuration reference Available environment variables =============================== -{% for group_name, vars in vars %} +{% for group_name, group_vars in vars %} {{group_name}} {{group_name|repeat_char:"-"}} -{% for var in vars %}* ``{{var.name}}``: {% if var.help_text %}{{var.help_text|safe|ensure_endswith:"."}}{% endif %}{% if var.auto_display_default and not var.default|is_undefined %} Defaults to: ``{{var.default|to_str|safe}}``.{% endif %} +{% for subgroup_name, subgroup_vars in group_vars %} + +{% if subgroup_name is not null %} +{{subgroup_name}} +{{subgroup_name|repeat_char:"^"}} +{% endif %} + +{% for var in group_vars %}* ``{{var.name}}``: {% if var.help_text %}{{var.help_text|safe|ensure_endswith:"."}}{% endif %}{% if var.auto_display_default and not var.default|is_undefined %} Defaults to: ``{{var.default|to_str|safe}}``.{% endif %} +{% endfor %} {% endfor %} {% endfor %}