-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
✨[#64] add setup configuration documentation generation
- Loading branch information
Showing
6 changed files
with
127 additions
and
1 deletion.
There are no files selected for viewing
51 changes: 51 additions & 0 deletions
51
open_api_framework/management/commands/generate_setup_config_docs.py
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
) | ||
) |
9 changes: 9 additions & 0 deletions
9
open_api_framework/templates/open_api_framework/components/setup_config_step.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 %} |
47 changes: 47 additions & 0 deletions
47
open_api_framework/templates/open_api_framework/setup_configuration.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters