📝 [#210] Update documentation for setup-configuration

docs/conf.py

@@ -8,12 +8,18 @@
 import os
 import sys
 
-# import django
+import django
+from django.utils.translation import activate
 
 sys.path.insert(0, os.path.abspath("../src"))
 
 import nrc  # noqa isort:skip
 
+from nrc.setup import setup_env  # noqa isort:skip
+
+setup_env()
+django.setup()
+
 # from nrc.setup import setup_env  # noqa isort:skip
 
 # TODO: This needs to be enabled when we want to use autodoc to grab
@@ -43,6 +49,9 @@
     "sphinx.ext.todo",
     "recommonmark",
     "sphinx_tabs.tabs",
+    "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.
@@ -55,6 +64,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/delivery_guarantees.rst

@@ -79,7 +79,7 @@ the formula to calculate the time to wait until the next retry is as follows:
 
 where `t` is time in seconds and  `c` is the number of retries that have been performed already.
 
-This behaviour can be configured using :ref:`setup_configuration <installation_configuration_cli_retry>`
+This behaviour can be configured using :ref:`setup_configuration <ref_step_notifications_api_common.contrib.setup_configuration.steps.NotificationConfigurationStep>`
 and also via the admin interface at **Configuratie > Notificatiescomponentconfiguratie**:
 
 * **Notification delivery max retries**: the maximum number of retries the task queue

docs/installation/configuration/opennotifs_config_cli.rst

@@ -1,116 +1,7 @@
 .. _installation_configuration_cli:
 
 =====================================
-Open Notificaties configuration (CLI)
+Open Notificaties Configuration (CLI)
 =====================================
 
-After deploying Open Notificaties, it needs to be configured to be fully functional. The
-command line tool ``setup_configuration`` assist with this configuration by loading a
-YAML file in which the configuration information is specified.
-
-.. code-block:: bash
-
-    src/manage.py setup_configuration --yaml-file /path/to/your/yaml
-
-You can get the full command documentation with:
-
-.. code-block:: bash
-
-    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 shape of the data,
-used by each step.
-
-
-Services configuration
-----------------------
-
-In order for Open Notificaties to make requests to external services (such as the Autorisaties API),
-``Services`` must be configured. To enable this step, set ``zgw_consumers_config_enable`` to ``true`` in your
-configuration file and specify a list of ``Services``, for example:
-
-.. code-block:: yaml
-
-    zgw_consumers_config_enable: true
-    zgw_consumers:
-    services:
-      # all possible configurable fields
-      - identifier: objecten-test
-        label: Objecten API test
-        api_root: http://objecten.local/api/v1/
-        api_connection_check_path: objects
-        api_type: orc
-        auth_type: api_key
-        header_key: Authorization
-        header_value: Token foo
-        client_id: client
-        secret: super-secret
-        nlx: http://some-outway-adress.local:8080/
-        user_id: open-formulieren
-        user_representation: Open Formulieren
-        timeout: 5
-      # minimum required fields
-      - identifier: objecttypen-test
-        label: Objecttypen API test
-        api_root: http://objecttypen.local/api/v1/
-        api_type: orc
-        auth_type: api_key
-
-Client credentials
-------------------
-
-TODO: add generated documentation for ``JWTSecretsConfigurationStep``
-
-
-Autorisaties API configuration
-------------------------------
-
-Open Notificaties uses Autorisaties API to check permissions of the clients that
-make requests to Open Notificaties.
-
-This step configures Open Notificaties to use the specified Autorisaties API (see also :ref:`installation_configuration`). It is
-dependent on the `Services configuration`_ step to load a ``Service`` for this Autorisaties API,
-which is referred to in this step by ``authorizations_api_service_identifier``.
-To enable this step, set ``autorisaties_api_config_enable`` to ``true`` in your
-configuration file and specify which ``Service`` to use as the Autorisaties API, for example:
-
-.. code-block:: yaml
-
-    autorisaties_api_config_enable: True
-    autorisaties_api:
-      authorizations_api_service_identifier: autorisaties-api
-
-.. _installation_configuration_cli_retry:
-
-Notificaties configuration
---------------------------
-
-TODO: add generated documentation
-
-
-Sites configuration
--------------------
-
-TODO: add generated documentation
-
-Execution
-=========
-
-Open Notificaties configuration
--------------------------------
-
-With the full command invocation, all defined configuration steps are applied. Each step is idempotent,
-so it's safe to run the command multiple times. The steps will overwrite any manual changes made in
-the admin if you run the command after making these changes.
-
-.. 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.in

@@ -4,7 +4,7 @@ open-api-framework
 markdown
 self-certifi
 furl
-django-setup-configuration>=0.5.0
+django-setup-configuration>=0.7.0
 zgw-consumers[setup-configuration]
 commonground-api-common[setup-configuration]
 notifications-api-common[setup-configuration]

requirements/base.txt

@@ -58,7 +58,7 @@ click-plugins==1.1.1
     # via celery
 click-repl==0.3.0
     # via celery
-commonground-api-common==2.2.0
+commonground-api-common==2.5.0
     # via
     #   -r requirements/base.in
     #   open-api-framework
@@ -103,7 +103,6 @@ django==4.2.17
     #   drf-nested-routers
     #   drf-spectacular
     #   drf-spectacular-sidecar
-    #   drf-yasg
     #   maykin-2fa
     #   mozilla-django-oidc
     #   mozilla-django-oidc-db
@@ -152,7 +151,7 @@ django-sendfile2==0.7.1
     # via django-privates
 django-sessionprofile==3.0.0
     # via open-api-framework
-django-setup-configuration==0.5.0
+django-setup-configuration==0.7.0
     # via
     #   -r requirements/base.in
     #   commonground-api-common
@@ -178,7 +177,6 @@ djangorestframework==3.15.2
     #   djangorestframework-inclusions
     #   drf-nested-routers
     #   drf-spectacular
-    #   drf-yasg
     #   notifications-api-common
     #   open-api-framework
 djangorestframework-camel-case==1.4.2
@@ -189,14 +187,16 @@ 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
-    # via open-api-framework
+    # via
+    #   commonground-api-common
+    #   open-api-framework
 drf-spectacular-sidecar==2024.7.1
     # via drf-spectacular
-drf-yasg==1.21.7
-    # via commonground-api-common
 ecs-logging==2.2.0
     # via elastic-apm
 elastic-apm==6.23.0
@@ -217,9 +217,7 @@ humanize==4.10.0
 idna==3.7
     # via requests
 inflection==0.5.1
-    # via
-    #   drf-spectacular
-    #   drf-yasg
+    # via drf-spectacular
 iso-639==0.4.5
     # via commonground-api-common
 isodate==0.6.1
@@ -244,11 +242,11 @@ 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
-notifications-api-common==0.4.0
+notifications-api-common==0.6.0
     # via
     #   -r requirements/base.in
     #   commonground-api-common
@@ -258,8 +256,6 @@ orderedmultidict==1.0.1
     # via furl
 oyaml==1.0
     # via commonground-api-common
-packaging==24.1
-    # via drf-yasg
 phonenumberslite==8.13.43
     # via django-two-factor-auth
 prometheus-client==0.20.0
@@ -299,13 +295,10 @@ python-dotenv==1.0.1
     #   open-api-framework
     #   pydantic-settings
 pytz==2024.1
-    # via
-    #   drf-yasg
-    #   flower
+    # via flower
 pyyaml==6.0.2
     # via
     #   drf-spectacular
-    #   drf-yasg
     #   oyaml
     #   pydantic-settings
 qrcode==7.4.2
@@ -332,6 +325,10 @@ rpds-py==0.20.0
     # via
     #   jsonschema
     #   referencing
+ruamel-yaml==0.18.10
+    # via django-setup-configuration
+ruamel-yaml-clib==0.2.12
+    # via ruamel-yaml
 self-certifi==1.0.0
     # via -r requirements/base.in
 sentry-sdk==2.12.0
@@ -360,7 +357,6 @@ uritemplate==4.1.1
     # via
     #   coreapi
     #   drf-spectacular
-    #   drf-yasg
 urllib3==2.2.2
     # via
     #   elastic-apm
@@ -381,7 +377,7 @@ webencodings==0.5.1
     # via bleach
 wrapt==1.16.0
     # via elastic-apm
-zgw-consumers==0.36.0
+zgw-consumers==0.37.0
     # via
     #   -r requirements/base.in
     #   commonground-api-common