Skip to content

Commit

Permalink
✨[#64] add setup configuration documentation generation
Browse files Browse the repository at this point in the history
  • Loading branch information
Coperh committed Jan 27, 2025
1 parent 939f48d commit 62b2a0d
Show file tree
Hide file tree
Showing 6 changed files with 127 additions and 1 deletion.
Original file line number Diff line number Diff line change
@@ -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
)
)
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{% load doc_tags %}
{% spaceless %}
{{ step_title }}
{{ step_title|repeat_char:"-"}}

{{ step_description }}

.. setup-config-example:: {{ step_path }}
{% endspaceless %}
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 7 additions & 0 deletions open_api_framework/templatetags/doc_tags.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

from decouple import Undefined

from open_api_framework.utils import get_configuraton_step_context

register = template.Library()


Expand Down Expand Up @@ -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)
12 changes: 12 additions & 0 deletions open_api_framework/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]

Expand Down

0 comments on commit 62b2a0d

Please sign in to comment.