diff --git a/docs/conf.py b/docs/conf.py index 0c582bb0..2d4c116c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,6 +9,7 @@ import sys import django +from django.utils.translation import activate sys.path.insert(0, os.path.abspath("../src")) os.environ["LOG_REQUESTS"] = "false" @@ -39,6 +40,9 @@ "sphinx.ext.autodoc", "sphinx.ext.todo", "sphinx.ext.intersphinx", + "sphinx.ext.autodoc", + "django_setup_configuration.documentation.setup_config_example", + "django_setup_configuration.documentation.setup_config_usage", # "sphinx_tabs.tabs", # "recommonmark", # "sphinx_markdown_tables", @@ -54,6 +58,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. diff --git a/docs/installation/setup_configuration.rst b/docs/installation/setup_configuration.rst index bf65f2e5..037bb4c0 100644 --- a/docs/installation/setup_configuration.rst +++ b/docs/installation/setup_configuration.rst @@ -4,84 +4,4 @@ Open Klant configuration (CLI) ============================== -After deploying Open Klant, it needs to be configured to be fully functional. -The django management command ``setup_configuration`` assist with this configuration. -You can get the full command documentation with: - -.. code-block:: bash - - python ./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. - -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, used by each step. - -Token configuration ----------------------- - -Create a (single) YAML configuration file with your settings: - -.. code-block:: yaml - - 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 - - - identifier: token-2 - token: 7b2b212d9f16d171a70a1d927cdcfbd5ca7a4799 - contact_person: Person 2 - email: person-2@example.com - - -Mozilla-django-oidc-db ----------------------- - -Create or update the (single) YAML configuration file with your settings: - -.. code-block:: yaml - - ... - 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_discovery_endpoint: https://keycloak.local/protocol/openid-connect/ - ... - -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. - -Execution -========= - -Open Klant configuration ------------------------- - -With the full command invocation, everything is configured at once. Each configuration step -is idempotent, so any manual changes made via the admin interface will be updated if the command -is run afterwards. - -.. code-block:: bash - - python ./src/manage.py setup_configuration --yaml-file /path/to/config.yaml - -.. note:: Due to a cache-bug in the underlying framework, you need to restart all - replicas for part of this change to take effect everywhere. +.. setup-config-usage:: diff --git a/requirements/base.txt b/requirements/base.txt index 202c6a20..13e9725e 100644 --- a/requirements/base.txt +++ b/requirements/base.txt @@ -151,7 +151,7 @@ django-sendfile2==0.7.1 # via django-privates django-sessionprofile==3.0.0 # via open-api-framework -django-setup-configuration==0.4.0 +django-setup-configuration==0.7.1 # via # -r requirements/base.in # mozilla-django-oidc-db @@ -184,6 +184,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 @@ -232,7 +234,7 @@ maykin-2fa==1.0.1 # via open-api-framework mozilla-django-oidc==4.0.1 # 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 @@ -315,6 +317,10 @@ rpds-py==0.19.1 # via # jsonschema # referencing +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 six==1.16.0 diff --git a/requirements/ci.in b/requirements/ci.in new file mode 100644 index 00000000..76375907 --- /dev/null +++ b/requirements/ci.in @@ -0,0 +1,2 @@ +codecov +pytest diff --git a/requirements/ci.txt b/requirements/ci.txt index 48907818..50390614 100644 --- a/requirements/ci.txt +++ b/requirements/ci.txt @@ -289,7 +289,7 @@ django-sessionprofile==3.0.0 # -c requirements/base.txt # -r requirements/base.txt # open-api-framework -django-setup-configuration==0.4.0 +django-setup-configuration==0.7.1 # via # -c requirements/base.txt # -r requirements/base.txt @@ -342,8 +342,11 @@ djangorestframework-inclusions==1.2.0 # -c requirements/base.txt # -r requirements/base.txt # open-api-framework -docutils==0.20.1 +docutils==0.21.2 # via + # -c requirements/base.txt + # -r requirements/base.txt + # django-setup-configuration # recommonmark # sphinx # sphinx-rtd-theme @@ -490,7 +493,7 @@ mozilla-django-oidc==4.0.1 # -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 @@ -686,6 +689,16 @@ rpds-py==0.19.1 # -r requirements/base.txt # jsonschema # referencing +ruamel-yaml==0.18.10 + # via + # -c requirements/base.txt + # -r requirements/base.txt + # django-setup-configuration +ruamel-yaml-clib==0.2.12 + # via + # -c requirements/base.txt + # -r requirements/base.txt + # ruamel-yaml sentry-sdk==2.12.0 # via # -c requirements/base.txt @@ -713,7 +726,7 @@ sphinx==7.4.7 # sphinxcontrib-jquery sphinx-markdown-tables==0.0.17 # via -r requirements/docs.in -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 diff --git a/requirements/dev.txt b/requirements/dev.txt index 3ce8815b..edd748f0 100644 --- a/requirements/dev.txt +++ b/requirements/dev.txt @@ -328,7 +328,7 @@ django-sessionprofile==3.0.0 # -c requirements/ci.txt # -r requirements/ci.txt # open-api-framework -django-setup-configuration==0.4.0 +django-setup-configuration==0.7.1 # via # -c requirements/ci.txt # -r requirements/ci.txt @@ -383,10 +383,11 @@ djangorestframework-inclusions==1.2.0 # -c requirements/ci.txt # -r requirements/ci.txt # open-api-framework -docutils==0.20.1 +docutils==0.21.2 # via # -c requirements/ci.txt # -r requirements/ci.txt + # django-setup-configuration # recommonmark # sphinx # sphinx-rtd-theme @@ -561,7 +562,7 @@ mozilla-django-oidc==4.0.1 # -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 @@ -799,6 +800,16 @@ rpds-py==0.19.1 # -r requirements/ci.txt # jsonschema # referencing +ruamel-yaml==0.18.10 + # via + # -c requirements/ci.txt + # -r requirements/ci.txt + # django-setup-configuration +ruamel-yaml-clib==0.2.12 + # via + # -c requirements/ci.txt + # -r requirements/ci.txt + # ruamel-yaml sentry-sdk==2.12.0 # via # -c requirements/ci.txt @@ -839,7 +850,7 @@ sphinx-markdown-tables==0.0.17 # via # -c requirements/ci.txt # -r requirements/ci.txt -sphinx-rtd-theme==2.0.0 +sphinx-rtd-theme==3.0.2 # via # -c requirements/ci.txt # -r requirements/ci.txt diff --git a/src/openklant/setup_configuration/models.py b/src/openklant/setup_configuration/models.py index 7d768d71..8ccb9379 100644 --- a/src/openklant/setup_configuration/models.py +++ b/src/openklant/setup_configuration/models.py @@ -16,6 +16,14 @@ class Meta: "administration", ) } + extra_kwargs = { + "identifier": {"examples": ["open-inwoner"]}, + "token": {"examples": ["modify-this"]}, + "contact_person": {"examples": ["John Doe"]}, + "email": {"examples": ["person@municipality.nl"]}, + "organization": {"examples": ["Municipality name"]}, + "application": {"examples": ["Open Inwoner"]}, + } class TokenAuthGroupConfigurationModel(ConfigurationModel): diff --git a/src/openklant/setup_configuration/steps.py b/src/openklant/setup_configuration/steps.py index 3a3df41e..96afb208 100644 --- a/src/openklant/setup_configuration/steps.py +++ b/src/openklant/setup_configuration/steps.py @@ -16,7 +16,7 @@ class TokenAuthConfigurationStep( BaseConfigurationStep[TokenAuthGroupConfigurationModel] ): """ - Configure configuration groups for the Objects API backend + Configure tokens for other applications to access the APIs provided by Open Klant """ namespace = "tokenauth" diff --git a/src/openklant/setup_configuration/tests/test_token_auth_config.py b/src/openklant/setup_configuration/tests/test_token_auth_config.py index 7a077172..825c409a 100644 --- a/src/openklant/setup_configuration/tests/test_token_auth_config.py +++ b/src/openklant/setup_configuration/tests/test_token_auth_config.py @@ -2,7 +2,10 @@ from django.test import TestCase -from django_setup_configuration.exceptions import ConfigurationRunFailed +from django_setup_configuration.exceptions import ( + ConfigurationRunFailed, + PrerequisiteFailed, +) from django_setup_configuration.test_utils import execute_single_step from openklant.components.token.models import TokenAuth @@ -218,7 +221,7 @@ def test_invalid_identifier(self): test_file_path = str(TEST_FILES / "token_invalid_identifier.yaml") - with self.assertRaises(ConfigurationRunFailed): + with self.assertRaises(PrerequisiteFailed): execute_single_step(TokenAuthConfigurationStep, yaml_source=test_file_path) tokens = TokenAuth.objects.order_by("created")