👷 [#501] Make sure docs are built in CI

* add sphinx dependencies to ci.in * add flag to run docs check * fix broken links
maykinmedia · Dec 19, 2024 · 57e036f · 57e036f
1 parent 82a93b9
commit 57e036f
Show file tree

Hide file tree

Showing 9 changed files with 116 additions and 67 deletions.
diff --git 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
@@ -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 <https://objects-and-objecttypes-api.readthedocs.io/en/latest/api/index.html>`__;
    2;Gepubliceerd op VNG-Realisatie Github omgeving en beschikbaar via Redoc en Swagger;No [1]_;
    3;Ontwerpbeslissing zijn vertaald naar (aanvullende) specificaties;`Yes <https://github.com/maykinmedia/objects-api/issues>`_;
-   4;Voldoet aan landelijke API strategie, in het bijzonder de core design rules;`Yes <https://objects-and-objecttypes-api.readthedocs.io/en/latest/api/principles.html>`__;
+   4;Voldoet aan landelijke API strategie, in het bijzonder de core design rules;`Yes <https://objects-and-objecttypes-api.readthedocs.io/en/latest/api/compliancy/api-strategy.html>`__;
    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 <https://github.com/maykinmedia/objects-api/actions?query=workflow%3Agenerate-sdks>`__, `2 <https://github.com/maykinmedia/objecttypes-api/actions?query=workflow%3Agenerate-sdks>`__);
@@ -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 <https://github.com/maykinmedia/objects-api/>`__, `2 <https://github.com/maykinmedia/objecttypes-api/>`__);
-   2;Testgevallen zijn beschreven voor elke service/operatie en aanvullende specificaties, zowel voor de happy als de unhappy flows;Yes (`1 <https://travis-ci.com/maykinmedia/objects-api>`__, `2 <https://travis-ci.com/maykinmedia/objecttypes-api>`__); 
+   2;Testgevallen zijn beschreven voor elke service/operatie en aanvullende specificaties, zowel voor de happy als de unhappy flows;Yes (`1 <https://github.com/maykinmedia/objects-api/actions>`__, `2 <https://github.com/maykinmedia/objecttypes-api/actions>`__);
    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
@@ -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
@@ -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
@@ -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               [email protected]
-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
@@ -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,16 +102,14 @@ 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:
@@ -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,15 +170,13 @@ Sites configuration
 
 .. code-block:: yaml
 
-   ...
     sites_config_enable: true
     sites_config:
       items:
       - domain: example.com
         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
@@ -30,9 +30,9 @@ changing the material history.
 Links
 =====
 
-* `Enterprise Architect (lite) <https://www.sparxsystems.eu/enterprise-architect/ea-lite-edition/>`__
+* `Enterprise Architect (lite) <https://sparxsystems.com/products/ea/trial/request.html>`__
 * :download:`Object and Objecttypes information model <_assets/information-model.zip>`
 * `MIM-files <https://register.geostandaarden.nl/informatiemodel/mim/>`__
 
 .. _`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
@@ -1,2 +1,8 @@
 codecov
 pytest
+
+# Documentation
+sphinx
+sphinx-rtd-theme
+sphinx-tabs
+recommonmark