✨ [#4882] Documentation for ConfigurationSteps

Using the YAML example directive from django-setup-configuration.
Also adds help texts and examples where needed to make sure these are picked up by the directive.

docs/conf.py

@@ -42,6 +42,7 @@
     "sphinx.ext.intersphinx",
     "sphinx_tabs.tabs",
     "sphinxcontrib.mermaid",
+    "django_setup_configuration.documentation.setup_config_example",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/installation/setup_configuration.rst

@@ -5,9 +5,13 @@ Open Forms configuration (CLI)
 ==============================
 
 After deploying Open Forms, it needs to be configured to be fully functional. The
-command line tool ``setup_configuration`` assist with this configuration by loading a
+command line tool ``setup_configuration`` assists 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
@@ -26,16 +30,40 @@ 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.
 
+All of the configuration must be part of a single YAML file that is passed to the command.
+
+OpenID Connect configuration for admin authentication
+-----------------------------------------------------
+
+.. autoclass:: mozilla_django_oidc_db.setup_configuration.steps.AdminOIDCConfigurationStep
+    :noindex:
+
+.. setup-config-example:: mozilla_django_oidc_db.setup_configuration.steps.AdminOIDCConfigurationStep
 
 Services configuration
 ----------------------
 
-TODO: add generated documentation for ``zgw_consumers.ServiceConfigurationStep``
+.. autoclass:: zgw_consumers.contrib.setup_configuration.steps.ServiceConfigurationStep
+    :noindex:
+
+.. setup-config-example:: zgw_consumers.contrib.setup_configuration.steps.ServiceConfigurationStep
+
 
 Objects API registration configuration
 --------------------------------------
 
-TODO: add generated documentation for ``ObjectsAPIConfigurationStep``
+.. autoclass:: openforms.contrib.objects_api.setup_configuration.steps.ObjectsAPIConfigurationStep
+    :noindex:
+
+.. setup-config-example:: openforms.contrib.objects_api.setup_configuration.steps.ObjectsAPIConfigurationStep
+
+ZGW APIs registration configuration
+-----------------------------------
+
+.. autoclass:: openforms.registrations.contrib.zgw_apis.setup_configuration.steps.ZGWApiConfigurationStep
+    :noindex:
+
+.. setup-config-example:: openforms.registrations.contrib.zgw_apis.setup_configuration.steps.ZGWApiConfigurationStep
 
 Execution
 =========
@@ -46,7 +74,3 @@ Open Forms 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.
-
-.. code-block:: bash
-
-    src/manage.py setup_configuration

src/openapi.yaml

@@ -9729,6 +9729,8 @@ components:
         apiRoot:
           type: string
           title: Api root url
+          description: The root URL of the service that will be used to construct
+            the URLs when making requests.
           maxLength: 255
         apiType:
           allOf:

src/openforms/contrib/objects_api/setup_configuration/models.py

@@ -7,30 +7,33 @@
 
 class SingleObjectsAPIGroupConfigModel(ConfigurationModel):
     objects_service_identifier: str = DjangoModelRef(
-        ObjectsAPIGroupConfig, "objects_service"
+        ObjectsAPIGroupConfig, "objects_service", examples=["objects-api"]
     )
     objecttypes_service_identifier: str = DjangoModelRef(
-        ObjectsAPIGroupConfig, "objecttypes_service"
+        ObjectsAPIGroupConfig, "objecttypes_service", examples=["objecttypes-api"]
     )
     documenten_service_identifier: str = DjangoModelRef(
-        ObjectsAPIGroupConfig, "drc_service", default=""
+        ObjectsAPIGroupConfig, "drc_service", default="", examples=["documenten-api"]
     )
     catalogi_service_identifier: str = DjangoModelRef(
-        ObjectsAPIGroupConfig, "catalogi_service", default=""
+        ObjectsAPIGroupConfig, "catalogi_service", default="", examples=["catalogi-api"]
     )
 
     # Renamed to be more descriptive
     document_type_submission_report: str = DjangoModelRef(
         ObjectsAPIGroupConfig,
         "iot_submission_report",
+        examples=["PDF Informatieobjecttype"],
     )
     document_type_submission_csv: str = DjangoModelRef(
         ObjectsAPIGroupConfig,
         "iot_submission_csv",
+        examples=["CSV Informatieobjecttype"],
     )
     document_type_attachment: str = DjangoModelRef(
         ObjectsAPIGroupConfig,
         "iot_attachment",
+        examples=["Attachment Informatieobjecttype"],
     )
 
     class Meta:
@@ -43,7 +46,14 @@ class Meta:
                 "organisatie_rsin",
             ]
         }
+        extra_kwargs = {
+            "identifier": {"examples": ["objects-api-acceptance"]},
+            "name": {"examples": ["Objecten acceptance environment"]},
+            "catalogue_domain": {"examples": ["ABCD"]},
+            "catalogue_rsin": {"examples": ["111222333"]},
+            "organisatie_rsin": {"examples": ["123456782"]},
+        }
 
 
 class ObjectsAPIGroupConfigModel(ConfigurationModel):
-    groups: list[SingleObjectsAPIGroupConfigModel] = Field(default_factory=list)
+    groups: list[SingleObjectsAPIGroupConfigModel] = Field()

src/openforms/contrib/objects_api/setup_configuration/steps.py

@@ -19,7 +19,8 @@ def get_service(slug: str) -> Service:
 
 class ObjectsAPIConfigurationStep(BaseConfigurationStep[ObjectsAPIGroupConfigModel]):
     """
-    Configure configuration groups for the Objects API backend
+    Configure groups for the Objects API backend. This step uses identifiers to refer to
+    Services that should be loaded by the previous step that loads Services.
     """
 
     verbose_name = "Configuration to set up Objects API registration backend services"

src/openforms/registrations/contrib/zgw_apis/migrations/0019_alter_zgwapigroupconfig_auteur.py

@@ -0,0 +1,23 @@
+# Generated by Django 4.2.18 on 2025-01-21 12:59
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("zgw_apis", "0018_alter_zgwapigroupconfig_drc_service_and_more"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="zgwapigroupconfig",
+            name="auteur",
+            field=models.CharField(
+                default="Aanvrager",
+                help_text="The value of the `author` field for documents that will be created in Documenten API",
+                max_length=200,
+                verbose_name="auteur",
+            ),
+        ),
+    ]

src/openforms/registrations/contrib/zgw_apis/models.py

@@ -142,6 +142,9 @@ class ZGWApiGroupConfig(models.Model):
     )
     auteur = models.CharField(
         _("auteur"),
+        help_text=_(
+            "The value of the `author` field for documents that will be created in Documenten API."
+        ),
         max_length=200,
         default="Aanvrager",
     )

src/openforms/registrations/contrib/zgw_apis/setup_configuration/models.py

@@ -21,16 +21,6 @@ class SingleZGWApiGroupConfigModel(ConfigurationModel):
         ZGWApiGroupConfig, "content_json"
     )
 
-    # FIXME choices and blank=True doesn't seem to be picked up properly
-    zaak_vertrouwelijkheidaanduiding: str = DjangoModelRef(
-        ZGWApiGroupConfig,
-        "zaak_vertrouwelijkheidaanduiding",
-        default="",
-    )
-    doc_vertrouwelijkheidaanduiding: str = DjangoModelRef(
-        ZGWApiGroupConfig, "doc_vertrouwelijkheidaanduiding", default=""
-    )
-
     class Meta:
         django_model_refs = {
             ZGWApiGroupConfig: [
@@ -40,9 +30,18 @@ class Meta:
                 "catalogue_rsin",
                 "organisatie_rsin",
                 "auteur",
+                "zaak_vertrouwelijkheidaanduiding",
+                "doc_vertrouwelijkheidaanduiding",
             ]
         }
+        extra_kwargs = {
+            "identifier": {"examples": ["open-zaak-acceptance"]},
+            "name": {"examples": ["Open Zaak acceptance environment"]},
+            "catalogue_domain": {"examples": ["ABCD"]},
+            "catalogue_rsin": {"examples": ["111222333"]},
+            "organisatie_rsin": {"examples": ["123456782"]},
+        }
 
 
 class ZGWApiGroupConfigModel(ConfigurationModel):
-    groups: list[SingleZGWApiGroupConfigModel] = Field(default_factory=list)
+    groups: list[SingleZGWApiGroupConfigModel] = Field()

src/openforms/registrations/contrib/zgw_apis/setup_configuration/steps.py

@@ -19,7 +19,8 @@ def get_service(slug: str) -> Service:
 
 class ZGWApiConfigurationStep(BaseConfigurationStep[ZGWApiGroupConfigModel]):
     """
-    Configure configuration groups for the ZGW API backend
+    Configure groups for the ZGW APIs registration backend. This step uses identifiers to refer to
+    Services that should be loaded by the previous step that loads Services.
     """
 
     verbose_name = "Configuration to set up ZGW API registration backend services"
@@ -41,8 +42,8 @@ def execute(self, model: ZGWApiGroupConfigModel):
                 "catalogue_domain": config.catalogue_domain,  # type: ignore
                 "catalogue_rsin": config.catalogue_rsin,  # type: ignore
                 "organisatie_rsin": config.organisatie_rsin,  # type: ignore
-                "zaak_vertrouwelijkheidaanduiding": config.zaak_vertrouwelijkheidaanduiding,
-                "doc_vertrouwelijkheidaanduiding": config.doc_vertrouwelijkheidaanduiding,
+                "zaak_vertrouwelijkheidaanduiding": config.zaak_vertrouwelijkheidaanduiding,  # type: ignore
+                "doc_vertrouwelijkheidaanduiding": config.doc_vertrouwelijkheidaanduiding,  # type: ignore
                 "auteur": config.auteur,  # type: ignore
                 "content_json": config.objects_api_json_content_template,
             }