diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 475a64ff..dda9f46b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -91,6 +91,7 @@ jobs: - store-reusable-workflow-vars with: main-branch: 'master' + run-docs: true python-version: '3.11' docker-image-name: ${{ needs.store-reusable-workflow-vars.outputs.image-name }} diff --git a/docs/api/compliancy/vng.rst b/docs/api/compliancy/vng.rst index 5a24536c..391766d4 100644 --- a/docs/api/compliancy/vng.rst +++ b/docs/api/compliancy/vng.rst @@ -5,12 +5,12 @@ VNG compliancy ============== The Objects and Objecttypes API specifications are proposed by the `municipality -of Utrecht`_ and submitted to the `VNG`_ for to become a Dutch national -standard. The VNG (Vereniging van Nederlandse Gemeenten) is the Association of +of Utrecht`_ and submitted to the `VNG`_ for to become a Dutch national +standard. The VNG (Vereniging van Nederlandse Gemeenten) is the Association of Dutch Municipalities. -The VNG has drafted an initial checklist for new API standards which is shown -in the table below. The table below also shows the compliancy to this checklist +The VNG has drafted an initial checklist for new API standards which is shown +in the table below. The table below also shows the compliancy to this checklist for both APIs. This checklist is only available in Dutch. .. csv-table:: 1. Stakeholder documentatie @@ -58,7 +58,7 @@ for both APIs. This checklist is only available in Dutch. 1;Opgesteld in Open API Specification 3.x;`Yes `__; 2;Gepubliceerd op VNG-Realisatie Github omgeving en beschikbaar via Redoc en Swagger;No [1]_; 3;Ontwerpbeslissing zijn vertaald naar (aanvullende) specificaties;`Yes `_; - 4;Voldoet aan landelijke API strategie, in het bijzonder de core design rules;`Yes `__; + 4;Voldoet aan landelijke API strategie, in het bijzonder de core design rules;`Yes `__; 5;Informatiebeveiliging en privacy best practices (IBD) worden gevolgd;No;Unclear 6;Aanvullende specificaties die het gedrag van de API specificeren voor de provider.;No;TODO 7;De OAS3-specificatie is getest voor toepasbaarheid in de mainstream code-generatoren;Yes (`1 `__, `2 `__); @@ -70,7 +70,7 @@ for both APIs. This checklist is only available in Dutch. :delim: ; 1;API-standaard is geïmplementeerd in een referentieimplementatie indien voor de standaard meerdere providers van toepassing kunnen zijn;Yes (`1 `__, `2 `__); - 2;Testgevallen zijn beschreven voor elke service/operatie en aanvullende specificaties, zowel voor de happy als de unhappy flows;Yes (`1 `__, `2 `__); + 2;Testgevallen zijn beschreven voor elke service/operatie en aanvullende specificaties, zowel voor de happy als de unhappy flows;Yes (`1 `__, `2 `__); 3;Elk testgeval beschrijft het logische testgeval, de teststap(pen) (wat wordt gedaan) en het verwachte resultaat;No;Unclear 4;Er zijn compliancy tests beschikbaar voor elke referentie-component (consumers en providers) en alle betreffende services en operaties, zodat leveranciers kunnen testen en aantonen dat hun applicatie voldoet aan de standaard;No;TODO 5;Voor zover nodig is ook de testdata beschreven die wordt gebruikt in de testgevallen;No;See 5.4. diff --git a/docs/api/index.rst b/docs/api/index.rst index 847cafc8..81112203 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -4,7 +4,7 @@ API-specifications ================== -The Objects API and Objecttypes API are scheduled to be a `recommended standard +The Objects API and Objecttypes API are scheduled to be a `recommended standard as of March 1, 2022`_. Their specifications can be found below. ====================== ========================================== @@ -22,7 +22,7 @@ API Specification version(s) See their respective repositories for the latest and previous versions. -.. _`recommended standard as of March 1, 2022`: https://www.vngrealisatie.nl/nieuws/twee-nieuwe-standaardverklaringen-deze-apis-maken-het-samenwerken-makkelijker-2022 +.. _`recommended standard as of March 1, 2022`: https://commonground.nl/news/view/0d7ff0a6-e960-412b-9a83-33bb1810c67d/twee-nieuwe-standaardverklaringen-deze-apis-maken-het-samenwerken-makkelijker-in-2022 .. _`Objecttypes API`: https://github.com/maykinmedia/objecttypes-api .. _`Objects API`: https://github.com/maykinmedia/objects-api diff --git a/docs/examples/objecttype-vordering.rst b/docs/examples/objecttype-vordering.rst index 4f5b6103..0a6dc732 100644 --- a/docs/examples/objecttype-vordering.rst +++ b/docs/examples/objecttype-vordering.rst @@ -5,13 +5,13 @@ Vordering (Debt claim) ====================== The "Vordering" objecttype is converted from an existing information model from -the `Gemeentelijke Basisprocessen Inkomen`_ (GBI). The GBI gemeenten work +the `Gemeentelijke Basisprocessen Inkomen`_ (GBI). The GBI gemeenten work together to create common proceses and models for the work-and-income domain. -As a test, they created a JSON schema for debt claims from their (huge) +As a test, they created a JSON schema for debt claims from their (huge) :download:`ontology <_assets/vordering-ontology.png>`. -.. _`Gemeentelijke Basisprocessen Inkomen`: https://gbi-gemeenten.nl/ +.. _`Gemeentelijke Basisprocessen Inkomen`: https://commonground.nl/groups/view/ea69810c-b776-489d-ae9b-8f0722db54fd/team-gemeentelijke-basisprocessen-inkomen-gbi Metadata ======== @@ -21,27 +21,27 @@ Attribute Value ======================== ========================== name vordering namePlural vorderingen -description -labels +description +labels maintainerOrganization GBI -maintainerDepartment +maintainerDepartment contactPerson Geurt-jan van Renswoude contactEmail Geurt-jan.van.Renswoude@ordina.nl -providerOrganization -source +providerOrganization +source status draft dataClassification open createdAt August 27, 2020 -modifiedAt -publishedAt -updateFrequency -documentationUrl +modifiedAt +publishedAt +updateFrequency +documentationUrl ======================== ========================== Schema ====== -You can download the JSON schema +You can download the JSON schema :download:`vordering.json <_assets/vordering.json>` or view it below: .. include:: _assets/vordering.json diff --git a/docs/installation/config_cli.rst b/docs/installation/config_cli.rst index 4445262a..281e414c 100644 --- a/docs/installation/config_cli.rst +++ b/docs/installation/config_cli.rst @@ -37,37 +37,37 @@ 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 - ... + + 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 @@ -81,7 +81,6 @@ In order to be able to retrieve objecttypes, a corresponding ``Service`` should created. An example of a configuration could be seen below: .. code-block:: yaml - ... zgw_consumers_config_enable: true zgw_consumers: @@ -102,15 +101,13 @@ created. An example of a configuration could be seen below: 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 - - ... + tokenauth_config_enable: true tokenauth: items: @@ -127,7 +124,6 @@ Create or update the (single) YAML configuration file with your settings: token: 7b2b212d9f16d171a70a1d927cdcfbd5ca7a4799 contact_person: Person 2 email: person-2@example.com - ... Mozilla-django-oidc-db ---------------------- @@ -136,7 +132,6 @@ 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: @@ -150,7 +145,6 @@ Create or update the (single) YAML configuration file with your settings: # 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. @@ -159,14 +153,13 @@ Sites configuration ------------------- 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 - ... zgw_consumers_config_enable: true zgw_consumers: @@ -184,7 +177,6 @@ item present that matches the ``notifications_api_service_identifier`` in the notification_delivery_max_retries: 1 notification_delivery_retry_backoff: 2 notification_delivery_retry_backoff_max: 3 - .... Execution diff --git a/docs/introduction/information-model.rst b/docs/introduction/information-model.rst index 73470b7b..a4f1a350 100644 --- a/docs/introduction/information-model.rst +++ b/docs/introduction/information-model.rst @@ -30,9 +30,9 @@ changing the material history. Links ===== -* `Enterprise Architect (lite) `__ +* `Enterprise Architect (lite) `__ * :download:`Object and Objecttypes information model <_assets/information-model.zip>` * `MIM-files `__ .. _`Metamodel Informatiemodellering`: https://www.geonovum.nl/geo-standaarden/metamodel-informatiemodellering-mim -.. _`StUF`: https://www.gemmaonline.nl/images/gemmaonline/f/fa/Stuf0301.pdf +.. _`StUF`: https://vng-realisatie.github.io/StUF-onderlaag/documenten/Stuf0301.pdf diff --git a/requirements/ci.in b/requirements/ci.in index 76375907..92e713a9 100644 --- a/requirements/ci.in +++ b/requirements/ci.in @@ -1,2 +1,7 @@ codecov pytest + +# Documentation +sphinx +sphinx-rtd-theme +sphinx-tabs diff --git a/requirements/ci.txt b/requirements/ci.txt index 82456248..fc54dcf5 100644 --- a/requirements/ci.txt +++ b/requirements/ci.txt @@ -4,6 +4,8 @@ # # pip-compile --no-emit-index-url --output-file=requirements/ci.txt requirements/base.txt requirements/ci.in requirements/test-tools.in # +alabaster==1.0.0 + # via sphinx amqp==5.2.0 # via # -r requirements/base.txt @@ -33,6 +35,8 @@ attrs==20.3.0 # -r requirements/base.txt # glom # jsonschema +babel==2.16.0 + # via sphinx beautifulsoup4==4.9.3 # via webtest billiard==4.2.0 @@ -288,6 +292,11 @@ djangorestframework-inclusions==1.2.0 # via # -r requirements/base.txt # open-api-framework +docutils==0.21.2 + # via + # sphinx + # sphinx-rtd-theme + # sphinx-tabs drf-nested-routers==0.94.1 # via # -r requirements/base.txt @@ -346,6 +355,8 @@ idna==3.7 # -r requirements/base.txt # requests # yarl +imagesize==1.4.1 + # via sphinx inflection==0.5.1 # via # -r requirements/base.txt @@ -371,6 +382,7 @@ jinja2==3.1.4 # via # -r requirements/base.txt # coreschema + # sphinx josepy==1.9.0 # via # -r requirements/base.txt @@ -427,6 +439,7 @@ packaging==23.2 # black # drf-yasg # pytest + # sphinx pathspec==0.12.1 # via black phonenumberslite==8.13.30 @@ -470,6 +483,10 @@ pydantic-settings[yaml]==2.6.1 # django-setup-configuration pyflakes==3.2.0 # via flake8 +pygments==2.18.0 + # via + # sphinx + # sphinx-tabs pyjwt==2.4.0 # via # -r requirements/base.txt @@ -537,6 +554,7 @@ requests==2.32.3 # mozilla-django-oidc # open-api-framework # requests-mock + # sphinx # zgw-consumers requests-mock==1.12.1 # via @@ -557,8 +575,34 @@ six==1.16.0 # python-dateutil # qrcode # webtest +snowballstemmer==2.2.0 + # via sphinx soupsieve==2.2.1 # via beautifulsoup4 +sphinx==8.1.3 + # via + # -r requirements/ci.in + # sphinx-rtd-theme + # sphinx-tabs + # sphinxcontrib-jquery +sphinx-rtd-theme==3.0.2 + # via -r requirements/ci.in +sphinx-tabs==3.4.7 + # via -r requirements/ci.in +sphinxcontrib-applehelp==2.0.0 + # via sphinx +sphinxcontrib-devhelp==2.0.0 + # via sphinx +sphinxcontrib-htmlhelp==2.1.0 + # via sphinx +sphinxcontrib-jquery==4.1 + # via sphinx-rtd-theme +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==2.0.0 + # via sphinx +sphinxcontrib-serializinghtml==2.0.0 + # via sphinx sqlparse==0.5.0 # via # -r requirements/base.txt