📝 Update setup config docs to use example directive

docs/conf.py

@@ -37,7 +37,10 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "django_setup_configuration.documentation.setup_config_example",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/setup_config.rst

@@ -1,14 +1,20 @@
 Setup configuration
 ===================
 
+This library has an optional integration with ``django-setup-configuration``, see the
+`documentation <https://django-setup-configuration.readthedocs.io/en/latest/>`_
+for more information on how to run ``setup_configuration``.
+To make use of this, you must install the ``setup-configuration`` dependency group:
+
+.. code-block:: bash
+
+    pip install commonground-api-common[setup-configuration]
+
+
 Loading JWTSecrets from a YAML file
-***************************************************
+***********************************
 
-This library provides a ``ConfigurationStep``
-(from the library ``django-setup-configuration``, see the
-`documentation <https://github.com/maykinmedia/django-setup-configuration>`_
-for more information on how to run ``setup_configuration``)
-to configure the client credentials.
+This library provides a ``ConfigurationStep`` to configure the client credentials.
 
 To add this step to your configuration steps, add ``django_setup_configuration`` to ``INSTALLED_APPS`` and add the following setting:
 
@@ -24,14 +30,30 @@ The YAML file that is passed to ``setup_configuration`` must set the
 ``vng_api_common_credentials_config_enable`` flag to ``true`` to enable the step. Any number of ``identifier`` and
 ``secret`` pairs can be defined under ``vng_api_common_credentials.items``
 
-Example file:
+You can use the following example YAML and adapt it to your needs:
+
+.. setup-config-example:: vng_api_common.contrib.setup_configuration.steps.JWTSecretsConfigurationStep
+
+
+Loading Applicaties from a YAML file
+************************************
+
+This library also provides a ``ConfigurationStep`` to configure the applicaties.
+
+To add this step to your configuration steps, add ``django_setup_configuration`` to ``INSTALLED_APPS`` and add the following setting:
+
+    .. code:: python
+
+        SETUP_CONFIGURATION_STEPS = [
+            ...
+            "vng_api_common.contrib.setup_configuration.steps.ApplicatieConfigurationStep"
+            ...
+        ]
+
+The YAML file that is passed to ``setup_configuration`` must set the
+``vng_api_common_applicaties_config_enable`` flag to ``true`` to enable the step.
+Any number of ``Applicaties`` can be defined under ``vng_api_common_applicaties.items``
 
-    .. code:: yaml
+You can use the following example YAML and adapt it to your needs:
 
-        vng_api_common_credentials_config_enable: True
-        vng_api_common_credentials:
-          items:
-          - identifier: user-id
-            secret: super-secret
-          - identifier: user-id2
-            secret: super-secret2
+.. setup-config-example:: vng_api_common.contrib.setup_configuration.steps.ApplicatieConfigurationStep

setup.cfg

@@ -90,7 +90,7 @@ tests =
 testutils =
     zgw-consumers-oas
 setup-configuration =
-    django-setup-configuration>=0.4.0
+    django-setup-configuration>=0.6.0
 pep8 = flake8
 coverage = pytest-cov
 docs =

vng_api_common/contrib/setup_configuration/models.py

@@ -13,10 +13,14 @@ class Meta:
                 "secret",
             ]
         }
+        extra_kwargs = {
+            "identifier": {"examples": ["application-name"]},
+            "secret": {"examples": ["modify-this"]},
+        }
 
 
 class JWTSecretsConfigurationModel(ConfigurationModel):
-    items: list[SingleJWTSecretConfigurationModel] = Field(default_factory=list)
+    items: list[SingleJWTSecretConfigurationModel] = Field()
 
 
 class SingleApplicatieConfigurationModel(ConfigurationModel):
@@ -26,7 +30,15 @@ class Meta:
         django_model_refs = {
             Applicatie: ["uuid", "client_ids", "label", "heeft_alle_autorisaties"]
         }
+        extra_kwargs = {
+            "uuid": {
+                # FIXME workaround for https://github.com/maykinmedia/django-setup-configuration/issues/58
+                "default": "17fd9f07-6b2f-4168-9262-d4d17c3e669b"
+            },
+            "client_ids": {"examples": [["open-notificaties-prod"]]},
+            "label": {"examples": ["Open Notificaties (productie)"]},
+        }
 
 
 class ApplicatieConfigurationModel(ConfigurationModel):
-    items: list[SingleApplicatieConfigurationModel] = Field(default_factory=list)
+    items: list[SingleApplicatieConfigurationModel] = Field()

vng_api_common/serializers.py

@@ -91,7 +91,7 @@ class ValidatieFoutSerializer(FoutSerializer):
 
 
 def add_choice_values_help_text(
-    choices: Union[models.Choices, List[Tuple[str, str]]]
+    choices: Union[models.Choices, List[Tuple[str, str]]],
 ) -> str:
     is_dj_choices = inspect.isclass(choices) and issubclass(choices, models.Choices)
 

vng_api_common/views.py

@@ -184,12 +184,12 @@ def _test_nrc_config(check_autorisaties_subscription=True) -> list:
     nrc_client: Optional[Client] = NotificationsConfig.get_client()
 
     if not nrc_client:
-        return [((_("NRC"), _("Missing"), False))]
+        return [(_("NRC"), _("Missing"), False)]
 
     has_nrc_auth = nrc_client.auth is not None if nrc_client else False
 
     if not nrc_config.notifications_api_service:
-        checks = [((_("NRC"), _("Missing"), False))]
+        checks = [(_("NRC"), _("Missing"), False)]
         return checks
 
     checks = [