✨[#64] add setup configuration documentation generation

open_api_framework/management/commands/generate_setup_config_docs.py

@@ -0,0 +1,51 @@
+from django.conf import settings
+from django.core.management.base import BaseCommand
+from django.template import loader
+
+from open_api_framework.utils import get_configuraton_step_context
+
+
+def render_step_info(step_name: str) -> str:
+    template = loader.get_template(
+        "open_api_framework/components/setup_config_step.rst"
+    )
+
+    context = get_configuraton_step_context(step_name)
+    return template.render(context)
+
+
+def convert_setup_configuration_steps_to_rst(
+    project_name: str, config_steps: list[str]
+) -> str:
+    template = loader.get_template("open_api_framework/setup_configuration.rst")
+    return template.render(
+        {"project_name": project_name, "setup_configuraiton_steps": config_steps}
+    )
+
+
+class Command(BaseCommand):
+    help = "Generate documentation for all used envvars"
+
+    def add_arguments(self, parser):
+        super().add_arguments(parser)
+
+        parser.add_argument(
+            "--file",
+            help="Name and path of the file to which the documentation will be written.",
+            nargs="?",
+            default="docs/setup_configuration.rst",
+        )
+
+    def handle(self, *args, **options):
+        file_path = options["file"]
+
+        configuration_steps = getattr(settings, "SETUP_CONFIGURATION_STEPS", [])
+
+        project_name = getattr(settings, "PROJECT_NAME", settings.PROJECT_DIRNAME)
+
+        with open(file_path, "w") as f:
+            f.write(
+                convert_setup_configuration_steps_to_rst(
+                    project_name, configuration_steps
+                )
+            )

open_api_framework/templates/open_api_framework/components/setup_config_step.rst

@@ -0,0 +1,9 @@
+{% load doc_tags %}
+{% spaceless %}
+{{ step_title }}
+{{ step_title|repeat_char:"-"}}
+
+{{ step_description }}
+
+.. setup-config-example:: {{ step_path }}
+{% endspaceless %}

open_api_framework/templates/open_api_framework/setup_configuration.rst

@@ -0,0 +1,47 @@
+{% load doc_tags %}.. _installation_configuration_cli:
+
+===================={{ project_name|repeat_char:"="}}
+{{ project_name }} configuration (CLI)
+===================={{ project_name|repeat_char:"="}}
+
+After deploying {{ project_name }}, it needs to be configured to be fully functional.
+The django management command ``setup_configuration`` assist with this configuration.
+You can get the full command documentation with:
+
+.. code-block:: bash
+
+    python ./src/manage.py setup_configuration --help
+
+.. warning:: This command is declarative - if configuration is manually changed after
+   running the command and you then run the exact same command again, the manual
+   changes will be reverted.
+
+Preparation
+===========
+
+The command executes the list of pluggable configuration steps, and each step
+requires specific configuration information, that should be prepared.
+Here is the description of all available configuration steps and the configuration
+format, used by each step.
+
+{% for step_path in setup_configuraiton_steps %}
+{% render_setup_configuraiton_step step_path %}
+{% endfor %}
+
+
+Execution
+=========
+
+{{ project_name }} configuration
+{{ project_name|repeat_char:"-"}}--------------
+
+With the full command invocation, everything is configured at once. Each configuration step
+is idempotent, so any manual changes made via the admin interface will be updated if the command
+is run afterwards.
+
+.. code-block:: bash
+
+    python ./src/manage.py setup_configuration --yaml-file /path/to/config.yaml
+
+.. note:: Due to a cache-bug in the underlying framework, you need to restart all
+   replicas for part of this change to take effect everywhere.

open_api_framework/templatetags/doc_tags.py

@@ -2,6 +2,8 @@
 
 from decouple import Undefined
 
+from open_api_framework.utils import get_configuraton_step_context
+
 register = template.Library()
 
 
@@ -33,3 +35,8 @@ def ensure_endswith(value, char):
     if not value.endswith(char):
         value += char
     return value
+
+
+@register.inclusion_tag("open_api_framework/components/setup_config_step.rst")
+def render_setup_configuraiton_step(step_path):
+    return get_configuraton_step_context(step_path)

open_api_framework/utils.py

@@ -2,7 +2,19 @@
 
 from django.conf import settings
 from django.contrib.sessions.backends.base import SessionBase
+from django.utils.module_loading import import_string
 
 
 def get_session_store() -> SessionBase:
     return import_module(settings.SESSION_ENGINE).SessionStore
+
+
+def get_configuraton_step_context(step_path: str) -> dict:
+    step = import_string(step_path)
+
+    context = {
+        "step_title": step_path.split(".")[-1],
+        "step_description": step.verbose_name,
+        "step_path": step_path,
+    }
+    return context

pyproject.toml

@@ -55,7 +55,7 @@ dependencies = [
     "celery>=5.4.0",
     "flower>=2.0.1",
     "maykin-2fa>=1.0.1",
-    "django-setup-configuration>=0.1.0",
+    "django-setup-configuration>=0.6.0",
     "django-sessionprofile>=3.0.0",
 ]