📝 [#324] Update documentation for setup-configuration

and use the directive provided by the library

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: person-1@example.com
-          organization: Organization XYZ # optional
-          application: Application XYZ # optional
-          administration: Administration XYZ # optional
-
-        - identifier: token-2
-          token: 7b2b212d9f16d171a70a1d927cdcfbd5ca7a4799
-          contact_person: Person 2
-          email: person-2@example.com
-
-
-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::

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": ["person@municipality.nl"]},
+            "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"