Merge pull request #331 from maykinmedia/feature/324-setup-config-docs

📝 [#324] Update documentation for setup-configuration

Author: stevenbal

docs/conf.py

@@ -9,6 +9,7 @@
 import sys
 
 import django
+from django.utils.translation import activate
 
 sys.path.insert(0, os.path.abspath("../src"))
 os.environ["LOG_REQUESTS"] = "false"
@@ -39,6 +40,9 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.autodoc",
+    "django_setup_configuration.documentation.setup_config_example",
+    "django_setup_configuration.documentation.setup_config_usage",
     # "sphinx_tabs.tabs",
     # "recommonmark",
     # "sphinx_markdown_tables",
@@ -54,6 +58,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.

docs/installation/setup_configuration.rst

@@ -4,84 +4,4 @@
 Open Klant configuration (CLI)
 ==============================
 
-After deploying Open Klant, 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:
-
-.. code-block:: yaml
-
-    tokenauth_config_enable: true
-    tokenauth:
-      items:
-        - identifier: token-1
-          token: ba9d233e95e04c4a8a661a27daffe7c9bd019067
-          contact_person: Person 1
-          email: [email protected]
-          organization: Organization XYZ # optional
-          application: Application XYZ # optional
-          administration: Administration XYZ # optional
-
-        - identifier: token-2
-          token: 7b2b212d9f16d171a70a1d927cdcfbd5ca7a4799
-          contact_person: Person 2
-          email: [email protected]
-
-
-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
-=========
-
-Open Klant 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.
+.. setup-config-usage::

requirements/base.txt

@@ -151,7 +151,7 @@ django-sendfile2==0.7.1
     # via django-privates
 django-sessionprofile==3.0.0
     # via open-api-framework
-django-setup-configuration==0.4.0
+django-setup-configuration==0.7.1
     # via
     #   -r requirements/base.in
     #   mozilla-django-oidc-db
@@ -184,6 +184,8 @@ djangorestframework-gis==1.0
     # via open-api-framework
 djangorestframework-inclusions==1.2.0
     # via open-api-framework
+docutils==0.21.2
+    # via django-setup-configuration
 drf-nested-routers==0.94.1
     # via commonground-api-common
 drf-spectacular==0.27.2
@@ -232,7 +234,7 @@ maykin-2fa==1.0.1
     # via open-api-framework
 mozilla-django-oidc==4.0.1
     # via mozilla-django-oidc-db
-mozilla-django-oidc-db==0.21.1
+mozilla-django-oidc-db==0.22.0
     # via
     #   -r requirements/base.in
     #   open-api-framework
@@ -315,6 +317,10 @@ rpds-py==0.19.1
     # via
     #   jsonschema
     #   referencing
+ruamel-yaml==0.18.10
+    # via django-setup-configuration
+ruamel-yaml-clib==0.2.12
+    # via ruamel-yaml
 sentry-sdk==2.12.0
     # via open-api-framework
 six==1.16.0

requirements/ci.in

@@ -0,0 +1,2 @@
+codecov
+pytest

requirements/ci.txt

@@ -289,7 +289,7 @@ django-sessionprofile==3.0.0
     #   -c requirements/base.txt
     #   -r requirements/base.txt
     #   open-api-framework
-django-setup-configuration==0.4.0
+django-setup-configuration==0.7.1
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
@@ -342,8 +342,11 @@ djangorestframework-inclusions==1.2.0
     #   -c requirements/base.txt
     #   -r requirements/base.txt
     #   open-api-framework
-docutils==0.20.1
+docutils==0.21.2
     # via
+    #   -c requirements/base.txt
+    #   -r requirements/base.txt
+    #   django-setup-configuration
     #   recommonmark
     #   sphinx
     #   sphinx-rtd-theme
@@ -490,7 +493,7 @@ mozilla-django-oidc==4.0.1
     #   -c requirements/base.txt
     #   -r requirements/base.txt
     #   mozilla-django-oidc-db
-mozilla-django-oidc-db==0.21.1
+mozilla-django-oidc-db==0.22.0
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
@@ -686,6 +689,16 @@ rpds-py==0.19.1
     #   -r requirements/base.txt
     #   jsonschema
     #   referencing
+ruamel-yaml==0.18.10
+    # via
+    #   -c requirements/base.txt
+    #   -r requirements/base.txt
+    #   django-setup-configuration
+ruamel-yaml-clib==0.2.12
+    # via
+    #   -c requirements/base.txt
+    #   -r requirements/base.txt
+    #   ruamel-yaml
 sentry-sdk==2.12.0
     # via
     #   -c requirements/base.txt
@@ -713,7 +726,7 @@ sphinx==7.4.7
     #   sphinxcontrib-jquery
 sphinx-markdown-tables==0.0.17
     # via -r requirements/docs.in
-sphinx-rtd-theme==2.0.0
+sphinx-rtd-theme==3.0.2
     # via -r requirements/docs.in
 sphinx-tabs==3.4.5
     # via -r requirements/docs.in

requirements/dev.txt

@@ -328,7 +328,7 @@ django-sessionprofile==3.0.0
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
     #   open-api-framework
-django-setup-configuration==0.4.0
+django-setup-configuration==0.7.1
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
@@ -383,10 +383,11 @@ djangorestframework-inclusions==1.2.0
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
     #   open-api-framework
-docutils==0.20.1
+docutils==0.21.2
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
+    #   django-setup-configuration
     #   recommonmark
     #   sphinx
     #   sphinx-rtd-theme
@@ -561,7 +562,7 @@ mozilla-django-oidc==4.0.1
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
     #   mozilla-django-oidc-db
-mozilla-django-oidc-db==0.21.1
+mozilla-django-oidc-db==0.22.0
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
@@ -799,6 +800,16 @@ rpds-py==0.19.1
     #   -r requirements/ci.txt
     #   jsonschema
     #   referencing
+ruamel-yaml==0.18.10
+    # via
+    #   -c requirements/ci.txt
+    #   -r requirements/ci.txt
+    #   django-setup-configuration
+ruamel-yaml-clib==0.2.12
+    # via
+    #   -c requirements/ci.txt
+    #   -r requirements/ci.txt
+    #   ruamel-yaml
 sentry-sdk==2.12.0
     # via
     #   -c requirements/ci.txt
@@ -839,7 +850,7 @@ sphinx-markdown-tables==0.0.17
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
-sphinx-rtd-theme==2.0.0
+sphinx-rtd-theme==3.0.2
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt

src/openklant/setup_configuration/models.py

@@ -16,6 +16,14 @@ class Meta:
                 "administration",
             )
         }
+        extra_kwargs = {
+            "identifier": {"examples": ["open-inwoner"]},
+            "token": {"examples": ["modify-this"]},
+            "contact_person": {"examples": ["John Doe"]},
+            "email": {"examples": ["[email protected]"]},
+            "organization": {"examples": ["Municipality name"]},
+            "application": {"examples": ["Open Inwoner"]},
+        }
 
 
 class TokenAuthGroupConfigurationModel(ConfigurationModel):

src/openklant/setup_configuration/steps.py

@@ -16,7 +16,7 @@ class TokenAuthConfigurationStep(
     BaseConfigurationStep[TokenAuthGroupConfigurationModel]
 ):
     """
-    Configure configuration groups for the Objects API backend
+    Configure tokens for other applications to access the APIs provided by Open Klant
     """
 
     namespace = "tokenauth"

src/openklant/setup_configuration/tests/test_token_auth_config.py

@@ -2,7 +2,10 @@
 
 from django.test import TestCase
 
-from django_setup_configuration.exceptions import ConfigurationRunFailed
+from django_setup_configuration.exceptions import (
+    ConfigurationRunFailed,
+    PrerequisiteFailed,
+)
 from django_setup_configuration.test_utils import execute_single_step
 
 from openklant.components.token.models import TokenAuth
@@ -218,7 +221,7 @@ def test_invalid_identifier(self):
 
         test_file_path = str(TEST_FILES / "token_invalid_identifier.yaml")
 
-        with self.assertRaises(ConfigurationRunFailed):
+        with self.assertRaises(PrerequisiteFailed):
             execute_single_step(TokenAuthConfigurationStep, yaml_source=test_file_path)
 
         tokens = TokenAuth.objects.order_by("created")