From b72e2ca972de48a18980e77275738a0ce5210c92 Mon Sep 17 00:00:00 2001 From: Steven Bal Date: Fri, 7 Feb 2025 16:43:29 +0100 Subject: [PATCH] :memo: [#43] Update documentation for setup-configuration to use directive provided by the library --- docs/conf.py | 15 ++++- docs/installation/index.rst | 2 +- docs/installation/setup_configuraiton.rst | 69 ----------------------- docs/installation/setup_configuration.rst | 7 +++ 4 files changed, 22 insertions(+), 71 deletions(-) delete mode 100644 docs/installation/setup_configuraiton.rst create mode 100644 docs/installation/setup_configuration.rst diff --git a/docs/conf.py b/docs/conf.py index 8fc9776..33599a8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -8,11 +8,17 @@ import os import sys +import django +from django.utils.translation import activate + sys.path.insert(0, os.path.abspath("../src")) import referentielijsten # noqa isort:skip -# from objects.setup import setup_env # noqa isort:skip +from referentielijsten.setup import setup_env # noqa isort:skip + +setup_env() +django.setup() # TODO: This needs to be enabled when we want to use autodoc to grab # documentation from classes and functions. However, enabling django.setup() @@ -42,6 +48,9 @@ # "sphinx_tabs.tabs", # "recommonmark", # "sphinx_markdown_tables", + "sphinx.ext.autodoc", + "django_setup_configuration.documentation.setup_config_example", + "django_setup_configuration.documentation.setup_config_usage", ] # Add any paths that contain templates here, relative to this directory. @@ -54,6 +63,10 @@ # Usually you set "language" from the command line for these cases. language = "en" +# Also set the language to English for Django, to make sure that any translatable text +# is also shown in English (for instance the help texts for setup configuration examples) +activate("en") + # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. diff --git a/docs/installation/index.rst b/docs/installation/index.rst index 48d1d4b..1b68f60 100644 --- a/docs/installation/index.rst +++ b/docs/installation/index.rst @@ -15,4 +15,4 @@ this. :caption: Further reading config - setup_configuraiton + setup_configuration diff --git a/docs/installation/setup_configuraiton.rst b/docs/installation/setup_configuraiton.rst deleted file mode 100644 index 7e08337..0000000 --- a/docs/installation/setup_configuraiton.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _installation_configuration_cli: - -===================================== -Referentielijsten configuration (CLI) -===================================== - -After deploying Referentielijsten, 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. - -Token configuration ----------------------- - -Create a (single) YAML configuration file with your settings: - - -Mozilla-django-oidc-db ----------------------- - -Create or update the (single) YAML configuration file with your settings: - -.. code-block:: yaml - - ... - oidc_db_config_enable: true - oidc_db_config_admin_auth: - items: - - identifier: admin-oidc - oidc_rp_client_id: client-id - oidc_rp_client_secret: secret - endpoint_config: - oidc_op_discovery_endpoint: https://keycloak.local/protocol/openid-connect/ - ... - -More details about configuring mozilla-django-oidc-db through ``setup_configuration`` -can be found at the _`documentation`: https://mozilla-django-oidc-db.readthedocs.io/en/latest/setup_configuration.html. - -Execution -========= - -Referentielijsten configuration -------------------------------- - -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. diff --git a/docs/installation/setup_configuration.rst b/docs/installation/setup_configuration.rst new file mode 100644 index 0000000..107dbb1 --- /dev/null +++ b/docs/installation/setup_configuration.rst @@ -0,0 +1,7 @@ +.. _installation_configuration_cli: + +===================================== +Referentielijsten configuration (CLI) +===================================== + +.. setup-config-usage::