📝 [#210] Update documentation for setup-configuration

with general info on how to use the command, as well as YAML examples per configuration step

docs/conf.py

@@ -8,12 +8,17 @@
 import os
 import sys
 
-# import django
+import django
 
 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 +48,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.

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 `setup_configuration <installation/configuration/opennotifs_config_cli.html#configuration-for-notificaties-api>`_
 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::

src/nrc/setup_configuration/models.py

@@ -37,7 +37,7 @@ class KanalenFilterConfigurationModel(ConfigurationModel):
 
 
 class AbonnementConfigurationItem(ConfigurationModel):
-    uuid: UUID4 = Field(description="The UUID for this Abonnement.")
+    uuid: UUID4 = Field(description="The UUID for this Abonnement.", examples=["dbb420a3-e589-43ef-98e3-429d9da91092"])
     kanalen: list[KanalenFilterConfigurationModel] = Field(
         description="A list of channels which are subscribed to"
     )