From 57e036f6e73cb8f67f9851844326afe7f04be607 Mon Sep 17 00:00:00 2001 From: Steven Bal Date: Thu, 19 Dec 2024 14:21:13 +0100 Subject: [PATCH] :construction_worker: [#501] Make sure docs are built in CI * add sphinx dependencies to ci.in * add flag to run docs check * fix broken links --- .github/workflows/ci.yml | 1 + docs/api/compliancy/vng.rst | 12 ++-- docs/api/index.rst | 4 +- docs/conf.py | 4 ++ docs/examples/objecttype-vordering.rst | 26 ++++----- docs/installation/config_cli.rst | 76 +++++++++++-------------- docs/introduction/information-model.rst | 4 +- requirements/ci.in | 6 ++ requirements/ci.txt | 50 ++++++++++++++++ 9 files changed, 116 insertions(+), 67 deletions(-) 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/conf.py b/docs/conf.py index a8121ab6..fc2a50ef 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -79,8 +79,12 @@ todo_include_todos = True +linkcheck_timeout = 10 linkcheck_ignore = [ r"https?://.*\.gemeente.nl", r"http://localhost:\d+/", r"https://.*sentry.*", + "https://github.com/maykinmedia/objects-api-performance", + "https://objects.municipality.nl/admin/", + "https://sparxsystems.com/products/ea/trial/request.html", # this raises 403 for crawlers probably? ] 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 40799877..9bc29555 100644 --- a/docs/installation/config_cli.rst +++ b/docs/installation/config_cli.rst @@ -37,38 +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. @@ -84,7 +83,6 @@ created. An example of a configuration could be seen below: .. code-block:: yaml - ... zgw_consumers_config_enable: true zgw_consumers: services: @@ -104,7 +102,6 @@ created. An example of a configuration could be seen below: auth_type: api_key header_key: Authorization header_value: Token b9f100590925b529664ed9d370f5f8da124b2c20 - ... Tokens configuration @@ -112,8 +109,7 @@ Tokens configuration Create or update the (single) YAML configuration file with your settings: .. code-block:: yaml - - ... + tokenauth_config_enable: true tokenauth: items: @@ -140,7 +136,6 @@ Create or update the (single) YAML configuration file with your settings: '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``. @@ -153,7 +148,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: @@ -167,7 +161,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. @@ -177,7 +170,6 @@ Sites configuration .. code-block:: yaml - ... sites_config_enable: true sites_config: items: @@ -185,7 +177,6 @@ Sites configuration name: Example site - domain: test.example.com name: Test site - ... 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 @@ -200,7 +191,6 @@ item present that matches the ``notifications_api_service_identifier`` in the .. code-block:: yaml - ... zgw_consumers_config_enable: true zgw_consumers: services: @@ -217,8 +207,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..dada2d7b 100644 --- a/requirements/ci.in +++ b/requirements/ci.in @@ -1,2 +1,8 @@ codecov pytest + +# Documentation +sphinx +sphinx-rtd-theme +sphinx-tabs +recommonmark diff --git a/requirements/ci.txt b/requirements/ci.txt index 82456248..af40972f 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==0.7.16 + # 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 @@ -101,6 +105,8 @@ commonground-api-common==2.1.0 # via # -r requirements/base.txt # open-api-framework +commonmark==0.9.1 + # via recommonmark coreapi==2.3.3 # via # -r requirements/base.txt @@ -288,6 +294,12 @@ djangorestframework-inclusions==1.2.0 # via # -r requirements/base.txt # open-api-framework +docutils==0.18.1 + # via + # recommonmark + # sphinx + # sphinx-rtd-theme + # sphinx-tabs drf-nested-routers==0.94.1 # via # -r requirements/base.txt @@ -346,6 +358,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 +385,7 @@ jinja2==3.1.4 # via # -r requirements/base.txt # coreschema + # sphinx josepy==1.9.0 # via # -r requirements/base.txt @@ -427,6 +442,7 @@ packaging==23.2 # black # drf-yasg # pytest + # sphinx pathspec==0.12.1 # via black phonenumberslite==8.13.30 @@ -470,6 +486,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 @@ -522,6 +542,8 @@ qrcode==6.1 # via # -r requirements/base.txt # django-two-factor-auth +recommonmark==0.7.1 + # via -r requirements/ci.in redis==3.5.3 # via # -r requirements/base.txt @@ -537,6 +559,7 @@ requests==2.32.3 # mozilla-django-oidc # open-api-framework # requests-mock + # sphinx # zgw-consumers requests-mock==1.12.1 # via @@ -557,8 +580,35 @@ six==1.16.0 # python-dateutil # qrcode # webtest +snowballstemmer==2.2.0 + # via sphinx soupsieve==2.2.1 # via beautifulsoup4 +sphinx==7.1.2 + # via + # -r requirements/ci.in + # recommonmark + # sphinx-rtd-theme + # sphinx-tabs + # sphinxcontrib-jquery +sphinx-rtd-theme==2.0.0 + # via -r requirements/ci.in +sphinx-tabs==3.4.4 + # 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