Merge pull request #527 from maykinmedia/feature/521-setup-config-docs

 📝 [#521] Update docs for setup-config

Author: annashamray

.github/workflows/ci.yml

@@ -86,11 +86,12 @@ jobs:
         id: image-name
 
   open-api-ci:
-    uses: maykinmedia/open-api-workflows/.github/workflows/ci.yml@v3.0.2
+    uses: maykinmedia/open-api-workflows/.github/workflows/ci.yml@v4.1.0
     needs:
       - store-reusable-workflow-vars
     with:
       main-branch: 'master'
+      apt-packages: 'libgdal-dev gdal-bin'
       run-docs: true
       django-settings-module: objects.conf.ci
       python-version: '3.11'

.readthedocs.yaml

@@ -8,12 +8,14 @@ sphinx:
   configuration: docs/conf.py
 
 build:
-  os: 'ubuntu-20.04'
+  os: 'ubuntu-22.04'
   apt_packages:
     - libxml2-dev
     - libxmlsec1-dev
     - libxmlsec1-openssl
     - wget
+    - libgdal-dev
+    - gdal-bin
   tools:
     python: '3.11'
 

docs/conf.py

@@ -8,9 +8,16 @@
 import os
 import sys
 
+import django
+from django.utils.translation import activate
+
 sys.path.insert(0, os.path.abspath("../src"))
 
 import objects  # noqa isort:skip
+from objects.setup import setup_env  # noqa isort:skip
+
+setup_env()
+django.setup()
 
 # from objects.setup import setup_env  # noqa isort:skip
 
@@ -41,6 +48,9 @@
     "sphinx.ext.todo",
     "sphinx_tabs.tabs",
     "recommonmark",
+    "sphinx.ext.autodoc",
+    "django_setup_configuration.documentation.setup_config_example",
+    "django_setup_configuration.documentation.setup_config_usage",
     #    "sphinx_markdown_tables",
 ]
 
@@ -54,6 +64,10 @@
 # Usually you set "language" from the command line for these cases.
 language = "en"
 
+# Also set the language to English for Django, to make sure that any translatable text
+# is also shown in English (for instance the help texts for setup configuration examples)
+activate("en")
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.

docs/installation/config_cli.rst

@@ -5,216 +5,73 @@
 Configuration (CLI)
 ===================
 
-After deploying Objecttypes API and Objects API, they need to be configured to be fully functional. The
-command line tool `setup_configuration`_ assist with this configuration:
-
-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.
-
-.. _`setup_configuration`: https://github.com/maykinmedia/django-setup-configuration/
-
-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 configuration
-format, use by each step.
+.. setup-config-usage::
+  :show_command_usage: true
+  :show_steps: false
+  :show_steps_toc: false
+  :show_steps_autodoc: false
 
 Objects API
 ===========
 
-Objecttypes configuration
--------------------------
-
-To configure objecttypes the following configuration could be used:
-
-.. code-block:: yaml
-
-    zgw_consumers_config_enable: true
-    zgw_consumers:
-    services:
-      - identifier: objecttypen-foo
-        label: Objecttypen API Foo
-        api_root: http://objecttypen.foo/api/v1/
-        api_type: orc
-        auth_type: api_key
-        header_key: Authorization
-        header_value: Token ba9d233e95e04c4a8a661a27daffe7c9bd019067
-
-      - identifier: objecttypen-bar
-        label: Objecttypen API Bar
-        api_root: http://objecttypen.bar/api/v1/
-        api_type: orc
-        auth_type: api_key
-        header_key: Authorization
-        header_value: Token b9f100590925b529664ed9d370f5f8da124b2c20
-
-    objecttypes_config_enable: true
-    objecttypes:
-      items:
-        - uuid: b427ef84-189d-43aa-9efd-7bb2c459e281
-          name: Object Type 1
-          service_identifier: objecttypen-foo
-
-        - uuid: b0e8553f-8b1a-4d55-ab90-6d02f1bcf2c2
-          name: Object Type 2
-          service_identifier: objecttypen-bar
-    ...
-
-.. note:: The ``uuid`` field will be used to lookup existing ``ObjectType``'s.
-
-Objecttypes require a corresponding ``Service`` to work correctly. Creating
-these ``Service``'s can be done by defining these in the same yaml file. ``Service``
-instances will be created before the ``ObjectType``'s are created.
-
-Objecttypes connection configuration
-------------------------------------
-
-In order to be able to retrieve objecttypes, a corresponding ``Service`` should be
-created. An example of a configuration could be seen below:
+.. setup-config-usage::
+  :show_command_usage: false
 
-.. code-block:: yaml
-
-    zgw_consumers_config_enable: true
-    zgw_consumers:
-      services:
-      - identifier: objecttypes-api-1
-        label: Objecttypes API 1
-        api_root: http://objecttypes-1.local/api/v1/
-        api_connection_check_path: objecttypes
-        api_type: orc
-        auth_type: api_key
-        header_key: Authorization
-        header_value: Token ba9d233e95e04c4a8a661a27daffe7c9bd019067
-      - identifier: objecttypes-api-2
-        label: Objecttypes API 2
-        api_root: http://objecttypes-2.local/api/v1/
-        api_connection_check_path: objecttypes
-        api_type: orc
-        auth_type: api_key
-        header_key: Authorization
-        header_value: Token b9f100590925b529664ed9d370f5f8da124b2c20
-
-
-Tokens configuration
---------------------
-Create or update the (single) YAML configuration file with your settings:
-
-.. code-block:: yaml
+Objecttypes API
+===============
 
-    tokenauth_config_enable: true
-    tokenauth:
-      items:
-        - identifier: token-1
-          token: ba9d233e95e04c4a8a661a27daffe7c9bd019067
-          contact_person: Person 1
-          email: person-1@example.com
-          organization: Organization XYZ # optional
-          application: Application XYZ # optional
-          administration: Administration XYZ # optional
-          permissions:
-            - object_type: b427ef84-189d-43aa-9efd-7bb2c459e281
-              mode: read_and_write
-
-        - identifier: token-2
-          token: 7b2b212d9f16d171a70a1d927cdcfbd5ca7a4799
-          contact_person: Person 2
-          email: person-2@example.com
-          permissions:
-            - object_type: b0e8553f-8b1a-4d55-ab90-6d02f1bcf2c2
-              mode: read_only
-              use_fields: true
-              fields:
-                '1':
-                  - record__data__leeftijd
-                  - record__data__kiemjaar
-
-.. note:: To ensure the proper functioning of the tokens, it is essential to first configure the ``objecttypes``.
-          Then, the token configuration must be completed to guarantee the correct configuration of the ``Permissions``.
-
-
-Mozilla-django-oidc-db
-----------------------
-
-Create or update the (single) YAML configuration file with your settings:
+.. FIXME these can currently only be included manually, because these docs are built in
+.. the objects API repo
 
-.. code-block:: yaml
+.. autoclass:: django_setup_configuration.contrib.sites.steps.SitesConfigurationStep
+  :noindex:
+.. setup-config-example:: django_setup_configuration.contrib.sites.steps.SitesConfigurationStep
 
-    oidc_db_config_enable: true
-    oidc_db_config_admin_auth:
-    items:
-      - identifier: admin-oidc
-        oidc_rp_client_id: client-id
-        oidc_rp_client_secret: secret
-        endpoint_config:
-          oidc_op_authorization_endpoint: https://example.com/realms/test/protocol/openid-connect/auth
-          oidc_op_token_endpoint: https://example.com/realms/test/protocol/openid-connect/token
-          oidc_op_user_endpoint: https://example.com/realms/test/protocol/openid-connect/userinfo
+.. autoclass:: mozilla_django_oidc_db.setup_configuration.steps.AdminOIDCConfigurationStep
+  :noindex:
+.. setup-config-example:: mozilla_django_oidc_db.setup_configuration.steps.AdminOIDCConfigurationStep
 
-      # workaround for https://github.com/maykinmedia/django-setup-configuration/issues/27
-      userinfo_claims_source: id_token
 
-More details about configuring mozilla-django-oidc-db through ``setup_configuration``
-can be found at the _`documentation`: https://mozilla-django-oidc-db.readthedocs.io/en/latest/setup_configuration.html.
+**objecttypes.setup_configuration.steps.token_auth.TokenAuthConfigurationStep**
+-------------------------------------------------------------------------------
 
-Sites configuration
--------------------
+Configure tokens with permissions for other applications to access Objectstypes API
 
 .. code-block:: yaml
 
-    sites_config_enable: true
-    sites_config:
-      items:
-      - domain: example.com
-        name: Example site
-      - domain: test.example.com
-        name: Test site
+  tokenauth_config_enable: true
+  tokenauth:
 
-More details about sites configuration through ``setup_configuration``
-can be found at the _`site documentation`: https://github.com/maykinmedia/django-setup-configuration/blob/main/docs/sites_config.rst
-
-
-Notifications configuration
----------------------------
-
-To configure sending notifications for the application ensure there is a ``services``
-item present that matches the ``notifications_api_service_identifier`` in the
-``notifications_config`` namespace:
-
-.. code-block:: yaml
+    # REQUIRED: true
+    items:
+      -
 
-    zgw_consumers_config_enable: true
-    zgw_consumers:
-      services:
-      - identifier: notifications-api
-        label: Notificaties API
-        api_root: http://notificaties.local/api/v1/
-        api_connection_check_path: notificaties
-        api_type: nrc
-        auth_type: api_key
+        # DESCRIPTION: A human-friendly label to refer to this token
+        # REQUIRED: true
+        identifier: objects-api
 
-    notifications_config_enable: true
-    notifications_config:
-      notifications_api_service_identifier: notifications-api
-      notification_delivery_max_retries: 1
-      notification_delivery_retry_backoff: 2
-      notification_delivery_retry_backoff_max: 3
+        # REQUIRED: true
+        token: modify-this
 
-Execution
-=========
+        # DESCRIPTION: Name of the person in the organization who can access the API
+        # REQUIRED: true
+        contact_person: example_string
 
+        # DESCRIPTION: Email of the person, who can access the API
+        # REQUIRED: true
+        email: example_string
 
-With the full command invocation, everything is configured at once and immediately
-tested.
+        # DESCRIPTION: Organization which has access to the API
+        # DEFAULT VALUE: ""
+        # REQUIRED: false
+        organization: example_string
 
-.. code-block:: bash
+        # DESCRIPTION: Application which has access to the API
+        # DEFAULT VALUE: ""
+        # REQUIRED: false
+        application: example_string
 
-    src/manage.py setup_configuration --yaml-file /path/to/config.yaml
+        # DESCRIPTION: Administration which has access to the API
+        # DEFAULT VALUE: ""
+        # REQUIRED: false
+        administration: example_string

requirements/base.txt

@@ -148,7 +148,7 @@ django-sendfile2==0.7.0
     # via django-privates
 django-sessionprofile==3.0.0
     # via open-api-framework
-django-setup-configuration==0.5.0
+django-setup-configuration==0.7.1
     # via
     #   -r requirements/base.in
     #   mozilla-django-oidc-db
@@ -183,6 +183,8 @@ djangorestframework-gis==1.0
     # via open-api-framework
 djangorestframework-inclusions==1.2.0
     # via open-api-framework
+docutils==0.21.2
+    # via django-setup-configuration
 drf-nested-routers==0.94.1
     # via commonground-api-common
 drf-spectacular==0.27.2
@@ -236,11 +238,11 @@ maykin-2fa==1.0.1
     # via open-api-framework
 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
     #   open-api-framework
-notifications-api-common==0.4.0
+notifications-api-common==0.6.0
     # via
     #   -r requirements/base.in
     #   commonground-api-common
@@ -312,6 +314,10 @@ requests==2.32.3
     #   zgw-consumers
 requests-mock==1.12.1
     # via commonground-api-common
+ruamel-yaml==0.18.10
+    # via django-setup-configuration
+ruamel-yaml-clib==0.2.12
+    # via ruamel-yaml
 sentry-sdk==2.12.0
     # via open-api-framework
 setuptools==75.6.0
@@ -360,7 +366,7 @@ webencodings==0.5.1
     # via bleach
 wrapt==1.14.1
     # via elastic-apm
-zgw-consumers==0.36.1
+zgw-consumers==0.37.0
     # via
     #   -r requirements/base.in
     #   commonground-api-common