✨[#64] add setup config rst templates

open_api_framework/management/commands/generate_envvar_docs.py

@@ -27,7 +27,101 @@ def convert_variables_to_rst(variables: list[EnvironmentVariable]) -> str:
     return template.render({"vars": vars})
 
 
-class Command(ConfigDocBase, BaseCommand):
+class SetupConfigDocs(ConfigDocBase):
+
+    def generate_config_file(self) -> str:
+
+        full_rendered_content = ""
+
+        if not hasattr(settings, "SETUP_CONFIGURATION_STEPS"):
+            return full_rendered_content
+
+        for config_string in settings.SETUP_CONFIGURATION_STEPS:
+            config_step = import_string(config_string)
+
+            config_settings = getattr(config_step, "config_settings", None)
+            if not config_settings or not config_settings.independent:
+                continue
+
+            rendered_content = self.render_doc(config_settings, config_step)
+            full_rendered_content += rendered_content
+
+        template = loader.get_template("open_api_framework/setup_config.rst")
+        rendered = template.render(
+            {"rendered_configuration_steps": full_rendered_content}
+        )
+
+        return rendered
+
+    def render_doc(self, config_settings, config_step) -> str:
+        """
+        Render a `ConfigSettings` documentation template with the following variables:
+            1. enable_setting
+            2. required_settings
+            3. optional_settings
+            4. detailed_info
+            5. title
+        """
+        # 1.
+        enable_setting = getattr(config_settings, "enable_setting", None)
+
+        # 2.
+        required_settings = [
+            name for name in getattr(config_settings, "required_settings", [])
+        ]
+
+        # additional settings from related configuration steps to embed
+        # the documentation of several steps into one
+        related_config_settings = [
+            config for config in getattr(config_settings, "related_config_settings", [])
+        ]
+        required_settings_related = self.extract_unique_settings(
+            [config.required_settings for config in related_config_settings]
+        )
+        optional_settings_related = self.extract_unique_settings(
+            [config.optional_settings for config in related_config_settings]
+        )
+
+        required_settings.extend(required_settings_related)
+        required_settings.sort()
+
+        optional_settings = config_settings.optional_settings
+        optional_settings.sort()
+
+        # 4.
+        detailed_info = self.get_detailed_info(
+            config_settings,
+            related_config_settings,
+        )
+        detailed_info.sort()
+
+        # 5.
+        title = self.format_display_name(config_step.verbose_name)
+
+        template_variables = {
+            "enable_setting": enable_setting,
+            "required_settings": required_settings,
+            "optional_settings": optional_settings,
+            "detailed_info": detailed_info,
+            "title": title,
+        }
+
+        template = loader.get_template(
+            "open_api_framework/components/setup_config_step.rst"
+        )
+        rendered = template.render(template_variables)
+
+        return rendered
+
+    def format_display_name(self, display_name: str) -> str:
+        """Underlines title with '=' to display as heading in rst file"""
+
+        heading_bar = "-" * len(display_name)
+        display_name_formatted = f"{display_name}\n{heading_bar}"
+        return display_name_formatted
+
+
+class Command(BaseCommand):
     help = "Generate documentation for all used envvars"
 
     def add_arguments(self, parser):
@@ -55,7 +149,8 @@ def handle(self, *args, **options):
         self.generate_regular_config_docs(*args, **options)
         self.generate_setup_config_docs(*args, **options)
 
-    def generate_regular_config_docs(self, *args, **options):
+    @staticmethod
+    def generate_regular_config_docs(*args, **options):
         from open_api_framework.conf.utils import ENVVAR_REGISTRY
 
         file_path = options["envvar_file"]
@@ -77,22 +172,13 @@ def _sort(envvar):
         with open(file_path, "w") as f:
             f.write(convert_variables_to_rst(sorted_registry))
 
-    def generate_setup_config_docs(self, *args, **options) -> None:
-        full_rendered_content = ""
+    @staticmethod
+    def generate_setup_config_docs(*args, **options) -> None:
 
         file_path = options["config_file"]
-        if not hasattr(settings, "SETUP_CONFIGURATION_STEPS"):
-            return
-
-        for config_string in settings.SETUP_CONFIGURATION_STEPS:
-            config_step = import_string(config_string)
+        doc_generator = SetupConfigDocs()
 
-            config_settings = getattr(config_step, "config_settings", None)
-            if not config_settings or not config_settings.independent:
-                continue
-
-            rendered_content = self.render_doc(config_settings, config_step)
-            full_rendered_content += rendered_content
+        full_rendered_content = doc_generator.generate_config_file()
 
         if len(full_rendered_content) > 0:
             with open(file_path, "w") as f:

open_api_framework/templates/open_api_framework/components/setup_config_step.rst

@@ -0,0 +1,26 @@
+{% load doc_tags %}
+{% spaceless %}
+{{ title }}
+
+Enable/Disable configuration:
+"""""""""""""""""""""""""""""
+
+::
+
+    {{ enable_setting }}
+
+{% if required_settings %}
+Required settings
+"""""""""""""""""
+{% for setting in required_settings %}
+* ``SECRET_KEY``: Secret key that's used for certain cryptographic utilities.
+{% endfor %}{% endif %}
+
+{% if optional_settings %}
+Optional Settings
+"""""""""""""""""
+{% for setting in optional_settings %}
+* ``SECRET_KEY``: Secret key that's used for certain cryptographic utilities.
+{% endfor %}{% endif %}
+
+{% endspaceless %}

open_api_framework/templates/open_api_framework/env_config.rst

@@ -11,13 +11,16 @@ Available environment variables
 
 {% for group_name, group_vars in vars %}
 {{group_name}}
-{{group_name|repeat_char:"-"}}{% for subgroup_name, subgroup_vars in group_vars %}
-{% if subgroup_name is not null %}
+{{group_name|repeat_char:"-"}}
+
+{% spaceless %}{% for subgroup_name, subgroup_vars in group_vars %}{% if subgroup_name is not null %}
 {{subgroup_name}}
-{{subgroup_name|repeat_char:"^"}}
-{% endif %}
-{% for var in subgroup_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 %}
+{{subgroup_name|repeat_char:"^"}}{% endif %}
+
+{% spaceless %}
+{% for var in subgroup_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 %}{% endspaceless %}{% endfor %}{% endspaceless %}
+
 {% endfor %}
 
 {% block extra %}{% endblock %}

open_api_framework/templates/open_api_framework/setup_config.rst

@@ -0,0 +1,16 @@
+{% load doc_tags %}.. _installation_setup_config:
+
+=============================
+Setup configuration reference
+=============================
+
+{% block intro %}
+Setup configuration description
+{% endblock %}
+
+Configuration Environment Variables
+===================================
+
+All configuration steps currently available:
+
+{{ rendered_configuration_steps | safe }}

tox.ini

@@ -27,7 +27,7 @@ extras =
 deps =
   django42: Django~=4.2.0
 commands =
-  py.test tests \
+  py.test tests -vv \
    --cov --cov-report xml:reports/coverage-{envname}.xml \
    {posargs}