Merge pull request #28 from maykinmedia/feature/setup-config-example

📝 Update setup config docs to use example directive

docs/conf.py

@@ -6,18 +6,21 @@
 
 # -- Path setup --------------------------------------------------------------
 
+import os
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import sys
 from pathlib import Path
 
-current_dir = Path(__file__).parent.parent
-code_directory = current_dir / "notifications_api_common"
-
-sys.path.insert(0, code_directory)
+import django
 
+_root_dir = Path(__file__).parent.parent.resolve()
+sys.path.insert(0, str(_root_dir))
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "testapp.settings")
+django.setup()
 
 # -- Project information -----------------------------------------------------
 
@@ -37,6 +40,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
+    "django_setup_configuration.documentation.setup_config_example",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/setup_config.rst

@@ -7,10 +7,16 @@ Loading notification configuration from a YAML file
 This library provides two ``ConfigurationStep`` implementations
 (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``): one to configure the 
+for more information on how to run ``setup_configuration``): one to configure the
 service and retry settings, another to configure notification endpoint subscriptions.
 
-To add these steps to your configuration steps, add ``django_setup_configuration`` 
+To make use of this, you must install the ``setup-configuration`` dependency group:
+
+.. code-block:: bash
+
+    pip install zgw-consumers[setup-configuration]
+
+To add these steps to your configuration steps, add ``django_setup_configuration``
 to ``INSTALLED_APPS`` and add the following settings:
 
     .. code:: python
@@ -24,31 +30,14 @@ to ``INSTALLED_APPS`` and add the following settings:
             ...
         ]
 
-The YAML file that is passed to ``setup_configuration`` must set the appropriate 
+The YAML file that is passed to ``setup_configuration`` must set the appropriate
 flag and fields for both steps:
 
 Example file:
 
-    .. code:: yaml
-
-        notifications_config_enable: True
-        notifications_config:
-          notifications_api_service_identifier: notifs-api
-          notification_delivery_max_retries: 1
-          notification_delivery_retry_backoff: 2
-          notification_delivery_retry_backoff_max: 3
-
-        notifications_subscriptions_config_enable: true
-        notifications_subscriptions_config:
-          items:
-            - identifier: my-subscription
-              callback_url: http://my/callback
-              client_id: the-client
-              secret: supersecret
-              uuid: 0f616bfd-aacc-4d85-a140-2af17a56217b
-              channels:
-                - Foo
-                - Bar
+.. setup-config-example:: notifications_api_common.contrib.setup_configuration.steps.NotificationConfigurationStep
+
+.. setup-config-example:: notifications_api_common.contrib.setup_configuration.steps.NotificationSubscriptionConfigurationStep
 
 Because ``notifications_api_service_identifier`` is required, it might also be useful
 to use the `ServiceConfigurationStep <https://zgw-consumers.readthedocs.io/en/latest/setup_config.html>`_

notifications_api_common/contrib/setup_configuration/models.py

@@ -6,8 +6,7 @@
 
 class NotificationConfigurationModel(ConfigurationModel):
     notifications_api_service_identifier: str = DjangoModelRef(
-        NotificationsConfig,
-        "notifications_api_service",
+        NotificationsConfig, "notifications_api_service", examples=["notificaties-api"]
     )
 
     class Meta:
@@ -22,7 +21,7 @@ class Meta:
 
 class SubscriptionConfigurationItem(ConfigurationModel):
     uuid: UUID4 = Field(
-        description="The UUID for this subscription. Must match the UUID of the corresponding `Abonnement` in Open Notificaties."
+        description="The UUID for this subscription. Must match the UUID of the corresponding `Abonnement` in Open Notificaties.",
     )
 
     channels: list[str] = DjangoModelRef(
@@ -40,6 +39,12 @@ class Meta:
                 "secret",
             ]
         }
+        extra_kwargs = {
+            "identifier": {"examples": ["open-zaak"]},
+            "callback_url": {"examples": ["https://example.com/api/webhook/"]},
+            "client_id": {"examples": ["open-notificaties"]},
+            "secret": {"examples": ["modify-this"]},
+        }
 
 
 class SubscriptionConfigurationModel(ConfigurationModel):

setup.cfg

@@ -71,7 +71,7 @@ tests =
 pep8 = flake8
 coverage = pytest-cov
 setup-configuration =
-    django-setup-configuration>=0.4.0
+    django-setup-configuration>=0.7.0
     furl
 docs =
     sphinx