👷 [#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 · c20a939 · c20a939
1 parent 160d5fd
commit c20a939
Show file tree

Hide file tree

Showing 9 changed files with 110 additions and 64 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,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: [email protected]
-   ...
 
 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
@@ -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,7 @@
 codecov
 pytest
+
+# Documentation
+sphinx
+sphinx-rtd-theme
+sphinx-tabs
diff --git 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