✨[#64] add subgroup to generate_envvar_docs

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:

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
 

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:"^"}}
+{% end if %}
+
+{% 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 %}