From 756bc6783ef574d261bcc8020b66b2f738750e5b Mon Sep 17 00:00:00 2001 From: Conor Holden Date: Wed, 2 Oct 2024 15:06:25 +0200 Subject: [PATCH] :sparkles:[#64] add setup config rst templates --- .../commands/generate_envvar_docs.py | 112 ++++++++++++++++-- .../components/setup_config_step.rst | 26 ++++ .../open_api_framework/setup_config.rst | 16 +++ 3 files changed, 141 insertions(+), 13 deletions(-) create mode 100644 open_api_framework/templates/open_api_framework/components/setup_config_step.rst create mode 100644 open_api_framework/templates/open_api_framework/setup_config.rst diff --git a/open_api_framework/management/commands/generate_envvar_docs.py b/open_api_framework/management/commands/generate_envvar_docs.py index fafaa1a..7689c1d 100644 --- a/open_api_framework/management/commands/generate_envvar_docs.py +++ b/open_api_framework/management/commands/generate_envvar_docs.py @@ -27,7 +27,98 @@ 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 +146,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 +169,16 @@ 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 + doc_generator = SetupConfigDocs() + + full_rendered_content = doc_generator.generate_config_file() - 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 if len(full_rendered_content) > 0: with open(file_path, "w") as f: diff --git a/open_api_framework/templates/open_api_framework/components/setup_config_step.rst b/open_api_framework/templates/open_api_framework/components/setup_config_step.rst new file mode 100644 index 0000000..ba70f00 --- /dev/null +++ b/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 %} diff --git a/open_api_framework/templates/open_api_framework/setup_config.rst b/open_api_framework/templates/open_api_framework/setup_config.rst new file mode 100644 index 0000000..8c9c1cb --- /dev/null +++ b/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 }}