Merge pull request #5020 from open-formulieren/feature/4882-document-…

…setup-config-steps

 📝 [#4882] Documentation for ConfigurationSteps

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.
@@ -82,6 +83,10 @@
         "https://objects-and-objecttypes-api.readthedocs.io/en/stable/",
         None,
     ),
+    "django-setup-configuration": (
+        "https://django-setup-configuration.readthedocs.io/en/stable/",
+        None,
+    ),
 }
 
 # -- Options for HTML output -------------------------------------------------

docs/installation/setup_configuration.rst

@@ -5,48 +5,48 @@ 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.
 
-You can get the full command documentation with:
+For general information on how the command line tool works, refer to the
+:external+django-setup-configuration:ref:`documentation <usage_docs>`.
 
-.. code-block:: bash
+Below are example configurations for all the configuration steps this application provides.
+They can be used as a starting point and combined into a single YAML to use as input for the command.
 
-    src/manage.py setup_configuration --help
+.. warning::
+    The values in the following YAML examples contain defaults and in some case dummy values, make sure to edit
+    values of i.e. identifiers, secrets and other fields that have dummy values!
 
-.. 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.
+OpenID Connect configuration for admin authentication
+-----------------------------------------------------
 
-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.
+.. 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``
-
-Execution
-=========
+.. autoclass:: openforms.contrib.objects_api.setup_configuration.steps.ObjectsAPIConfigurationStep
+    :noindex:
 
-Open Forms configuration
-------------------------
+.. setup-config-example:: openforms.contrib.objects_api.setup_configuration.steps.ObjectsAPIConfigurationStep
 
-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.
+ZGW APIs registration configuration
+-----------------------------------
 
-.. code-block:: bash
+.. autoclass:: openforms.registrations.contrib.zgw_apis.setup_configuration.steps.ZGWApiConfigurationStep
+    :noindex:
 
-    src/manage.py setup_configuration
+.. setup-config-example:: openforms.registrations.contrib.zgw_apis.setup_configuration.steps.ZGWApiConfigurationStep

requirements/base.txt

@@ -199,7 +199,7 @@ django-sendfile2==0.7.1
     # via django-privates
 django-sessionprofile==2.0.0
     # via django-digid-eherkenning
-django-setup-configuration==0.4.0
+django-setup-configuration==0.6.0
     # via
     #   mozilla-django-oidc-db
     #   zgw-consumers
@@ -235,6 +235,8 @@ djangorestframework==3.15.2
     #   drf-spectacular
 djangorestframework-camel-case==1.4.2
     # via -r requirements/base.in
+docutils==0.21.2
+    # via django-setup-configuration
 drf-jsonschema-serializer==3.0.0
     # via -r requirements/base.in
 drf-nested-routers==0.93.4
@@ -331,7 +333,7 @@ maykin-python3-saml==1.16.1
     # via django-digid-eherkenning
 mozilla-django-oidc==4.0.0
     # via mozilla-django-oidc-db
-mozilla-django-oidc-db==0.21.1
+mozilla-django-oidc-db==0.22.0
     # via
     #   -r requirements/base.in
     #   django-digid-eherkenning
@@ -467,8 +469,12 @@ rpds-py==0.18.0
     #   referencing
 rstr==3.2.2
     # via schwifty
-ruamel-yaml==0.18.6
-    # via prance
+ruamel-yaml==0.18.10
+    # via
+    #   django-setup-configuration
+    #   prance
+ruamel-yaml-clib==0.2.12
+    # via ruamel-yaml
 schwifty==2024.5.3
     # via -r requirements/base.in
 self-certifi==1.0.0
@@ -565,7 +571,7 @@ xmltodict==0.12.0
     # via -r requirements/base.in
 zeep==4.2.1
     # via -r requirements/base.in
-zgw-consumers==0.36.0
+zgw-consumers==0.37.0
     # via -r requirements/base.in
 zopfli==0.2.3
     # via fonttools

requirements/ci.txt

@@ -344,7 +344,7 @@ django-sessionprofile==2.0.0
     #   -c requirements/base.txt
     #   -r requirements/base.txt
     #   django-digid-eherkenning
-django-setup-configuration==0.4.0
+django-setup-configuration==0.6.0
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
@@ -399,8 +399,11 @@ djangorestframework-camel-case==1.4.2
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
-docutils==0.20.1
+docutils==0.21.2
     # via
+    #   -c requirements/base.txt
+    #   -r requirements/base.txt
+    #   django-setup-configuration
     #   sphinx
     #   sphinx-rtd-theme
     #   sphinx-tabs
@@ -607,7 +610,7 @@ mozilla-django-oidc==4.0.0
     #   -c requirements/base.txt
     #   -r requirements/base.txt
     #   mozilla-django-oidc-db
-mozilla-django-oidc-db==0.21.1
+mozilla-django-oidc-db==0.22.0
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
@@ -898,11 +901,17 @@ rstr==3.2.2
     #   -c requirements/base.txt
     #   -r requirements/base.txt
     #   schwifty
-ruamel-yaml==0.18.6
+ruamel-yaml==0.18.10
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
+    #   django-setup-configuration
     #   prance
+ruamel-yaml-clib==0.2.12
+    # via
+    #   -c requirements/base.txt
+    #   -r requirements/base.txt
+    #   ruamel-yaml
 schwifty==2024.5.3
     # via
     #   -c requirements/base.txt
@@ -955,7 +964,7 @@ sphinx==7.3.0
     #   sphinx-rtd-theme
     #   sphinx-tabs
     #   sphinxcontrib-jquery
-sphinx-rtd-theme==2.0.0
+sphinx-rtd-theme==3.0.2
     # via -r requirements/docs.in
 sphinx-tabs==3.4.5
     # via -r requirements/docs.in
@@ -1119,7 +1128,7 @@ zeep==4.2.1
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
-zgw-consumers==0.36.0
+zgw-consumers==0.37.0
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt

requirements/dev.txt

@@ -373,7 +373,7 @@ django-sessionprofile==2.0.0
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
     #   django-digid-eherkenning
-django-setup-configuration==0.4.0
+django-setup-configuration==0.6.0
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
@@ -431,10 +431,11 @@ djangorestframework-camel-case==1.4.2
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
-docutils==0.20.1
+docutils==0.21.2
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
+    #   django-setup-configuration
     #   sphinx
     #   sphinx-rtd-theme
     #   sphinx-tabs
@@ -673,7 +674,7 @@ mozilla-django-oidc==4.0.0
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
     #   mozilla-django-oidc-db
-mozilla-django-oidc-db==0.21.1
+mozilla-django-oidc-db==0.22.0
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
@@ -998,11 +999,17 @@ rstr==3.2.2
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
     #   schwifty
-ruamel-yaml==0.18.6
+ruamel-yaml==0.18.10
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
+    #   django-setup-configuration
     #   prance
+ruamel-yaml-clib==0.2.12
+    # via
+    #   -c requirements/ci.txt
+    #   -r requirements/ci.txt
+    #   ruamel-yaml
 schwifty==2024.5.3
     # via
     #   -c requirements/ci.txt
@@ -1064,7 +1071,7 @@ sphinx==7.3.0
     #   sphinx-rtd-theme
     #   sphinx-tabs
     #   sphinxcontrib-jquery
-sphinx-rtd-theme==2.0.0
+sphinx-rtd-theme==3.0.2
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
@@ -1281,7 +1288,7 @@ zeep==4.2.1
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
-zgw-consumers==0.36.0
+zgw-consumers==0.37.0
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt

requirements/extensions.txt

@@ -330,7 +330,7 @@ django-sessionprofile==2.0.0
     #   -c requirements/base.txt
     #   -r requirements/base.txt
     #   django-digid-eherkenning
-django-setup-configuration==0.4.0
+django-setup-configuration==0.6.0
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
@@ -382,6 +382,11 @@ djangorestframework-camel-case==1.4.2
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
+docutils==0.21.2
+    # via
+    #   -c requirements/base.txt
+    #   -r requirements/base.txt
+    #   django-setup-configuration
 drf-jsonschema-serializer==3.0.0
     # via
     #   -c requirements/base.txt
@@ -555,7 +560,7 @@ mozilla-django-oidc==4.0.0
     #   -c requirements/base.txt
     #   -r requirements/base.txt
     #   mozilla-django-oidc-db
-mozilla-django-oidc-db==0.21.1
+mozilla-django-oidc-db==0.22.0
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
@@ -809,11 +814,17 @@ rstr==3.2.2
     #   -c requirements/base.txt
     #   -r requirements/base.txt
     #   schwifty
-ruamel-yaml==0.18.6
+ruamel-yaml==0.18.10
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
+    #   django-setup-configuration
     #   prance
+ruamel-yaml-clib==0.2.12
+    # via
+    #   -c requirements/base.txt
+    #   -r requirements/base.txt
+    #   ruamel-yaml
 schwifty==2024.5.3
     # via
     #   -c requirements/base.txt
@@ -979,7 +990,7 @@ zeep==4.2.1
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
-zgw-consumers==0.36.0
+zgw-consumers==0.37.0
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt