[#29] Add initial documentation

CHANGELOG.rst

@@ -0,0 +1,22 @@
+
+0.0.x (TBD)
+-----------
+* Documentation on https://open-producten.readthedocs.io/
+
+0.0.2 (17-01-2025)
+------------------
+
+0.0.1 (02-01-2025)
+------------------
+
+🎉 First release of Open Producten.
+
+Features:
+
+* Producttype API
+* Vragen API
+* Prijzen API
+* Themas API
+* Links API
+* Bestanden API
+* Automated test suite

LICENSE.md

@@ -1,6 +1,6 @@
 # Licence
 
-Copyright © Maykin {% now "Y" %}
+Copyright © Maykin {% now "Y" %} # FIXME
 
 Licensed under the EUPL
 
@@ -215,15 +215,15 @@ Deze openbare licentie van de Europese Unie („EUPL”) is van toepassing op he
 of op een andere wijze zijn bereidheid te kennen heeft gegeven krachtens de EUPL in licentie te geven.
 
 1.Definities
-In deze licentie wordt verstaan onder:  
-— „de licentie”:de onderhavige licentie;  
-— „het oorspronkelijke werk”:het werk dat of de software die door de licentiegever krachtens deze licentie wordt verspreid of medegedeeld, en dat/die beschikbaar is als broncode en, in voorkomend geval, ook als uitvoerbare code;  
-— „bewerkingen”:de werken of software die de licentiehouder kan creëren op grond van het oorspronkelijke werk of wijzigingen ervan. In deze licentie wordt niet gedefinieerd welke mate van wijziging of afhankelijkheid van het oorspronkelijke werk vereist is om een werk als een bewerking te kunnen aanmerken; dat wordt bepaald conform het auteursrecht dat van toepassing is in de in artikel 15 bedoelde staat;  
-— „het werk”:het oorspronkelijke werk of de bewerkingen ervan;  
-— „de broncode”:de voor mensen leesbare vorm van het werk, die het gemakkelijkste door mensen kan worden bestudeerd en gewijzigd;  
-— „de uitvoerbare code”:elke code die over het algemeen is gecompileerd en is bedoeld om door een computer als een programma te worden uitgevoerd;  
-— „de licentiegever”:de natuurlijke of rechtspersoon die het werk krachtens de licentie verspreidt of mededeelt;  
-— „bewerker(s)”:elke natuurlijke of rechtspersoon die het werk krachtens de licentie wijzigt of op een andere wijze bijdraagt tot de totstandkoming van een bewerking;  
+In deze licentie wordt verstaan onder:
+— „de licentie”:de onderhavige licentie;
+— „het oorspronkelijke werk”:het werk dat of de software die door de licentiegever krachtens deze licentie wordt verspreid of medegedeeld, en dat/die beschikbaar is als broncode en, in voorkomend geval, ook als uitvoerbare code;
+— „bewerkingen”:de werken of software die de licentiehouder kan creëren op grond van het oorspronkelijke werk of wijzigingen ervan. In deze licentie wordt niet gedefinieerd welke mate van wijziging of afhankelijkheid van het oorspronkelijke werk vereist is om een werk als een bewerking te kunnen aanmerken; dat wordt bepaald conform het auteursrecht dat van toepassing is in de in artikel 15 bedoelde staat;
+— „het werk”:het oorspronkelijke werk of de bewerkingen ervan;
+— „de broncode”:de voor mensen leesbare vorm van het werk, die het gemakkelijkste door mensen kan worden bestudeerd en gewijzigd;
+— „de uitvoerbare code”:elke code die over het algemeen is gecompileerd en is bedoeld om door een computer als een programma te worden uitgevoerd;
+— „de licentiegever”:de natuurlijke of rechtspersoon die het werk krachtens de licentie verspreidt of mededeelt;
+— „bewerker(s)”:elke natuurlijke of rechtspersoon die het werk krachtens de licentie wijzigt of op een andere wijze bijdraagt tot de totstandkoming van een bewerking;
 — „de licentiehouder” of „u”:elke natuurlijke of rechtspersoon die het werk onder de voorwaarden van de licentie gebruikt;  — „verspreiding” of „mededeling”:het verkopen, geven, uitlenen, verhuren, verspreiden, mededelen, doorgeven, of op een andere wijze online of offline beschikbaar stellen van kopieën van het werk of het verlenen van toegang tot de essentiële functies ervan ten behoeve van andere natuurlijke of rechtspersonen.
 
 2.Draagwijdte van de uit hoofde van de licentie verleende rechten
@@ -263,7 +263,7 @@ De oorspronkelijke licentiegever garandeert dat hij houder is van het hierbij ve
 Het werk is een werk in ontwikkeling, dat voortdurend door vele bewerkers wordt verbeterd. Het is een onvoltooid werk, dat bijgevolg nog tekortkomingen of programmeerfouten („bugs”) kan vertonen, die onlosmakelijk verbonden zijn met dit soort ontwikkeling. Om die reden wordt het werk op grond van de licentie verstrekt „zoals het is” en zonder enige garantie met betrekking tot het werk te geven, met inbegrip van, maar niet beperkt tot garanties met betrekking tot de verhandelbaarheid, de geschiktheid voor een specifiek doel, de afwezigheid van tekortkomingen of fouten, de nauwkeurigheid, de eerbiediging van andere intellectuele-eigendomsrechten dan het in artikel 6 van deze licentie bedoelde auteursrecht. Deze uitsluiting van garantie is een essentieel onderdeel van de licentie en een voorwaarde voor de verlening van rechten op het werk.
 
 8.Uitsluiting van aansprakelijkheid
-Behoudens in het geval van een opzettelijke fout of directe schade aan natuurlijke personen, is de licentiegever in geen enkel geval aansprakelijk voor ongeacht welke directe of indirecte, materiële of immateriële schade die voortvloeit uit de licentie of het gebruik van het werk, met inbegrip van, maar niet beperkt tot schade als gevolg van het verlies van goodwill, verloren werkuren, een computerdefect of computerfout, het verlies van gegevens, of enige andere commerciële schade, zelfs indien de licentiegever werd gewezen op de mogelijkheid van dergelijke schade. De licentiegever is echter aansprakelijk op grond van de wetgeving inzake productaansprakelijkheid, voor zover deze wetgeving op het werk van toepassing is. 
+Behoudens in het geval van een opzettelijke fout of directe schade aan natuurlijke personen, is de licentiegever in geen enkel geval aansprakelijk voor ongeacht welke directe of indirecte, materiële of immateriële schade die voortvloeit uit de licentie of het gebruik van het werk, met inbegrip van, maar niet beperkt tot schade als gevolg van het verlies van goodwill, verloren werkuren, een computerdefect of computerfout, het verlies van gegevens, of enige andere commerciële schade, zelfs indien de licentiegever werd gewezen op de mogelijkheid van dergelijke schade. De licentiegever is echter aansprakelijk op grond van de wetgeving inzake productaansprakelijkheid, voor zover deze wetgeving op het werk van toepassing is.
 
 9.Aanvullende overeenkomsten
 Bij de verspreiding van het werk kunt u ervoor kiezen een aanvullende overeenkomst te sluiten, waarin de verplichtingen of diensten overeenkomstig deze licentie worden omschreven. Indien deze verplichtingen worden aanvaard, kunt u echter alleen in eigen naam en onder eigen verantwoordelijkheid handelen, en dus niet in naam van de oorspronkelijke licentiegever of een bewerker, en kunt u voorts alleen handelen indien u ermee instemt alle bewerkers schadeloos te stellen, te verdedigen of te vrijwaren met betrekking tot de aansprakelijkheid van of vorderingen tegen deze bewerkers op grond van het feit dat u een garantie of aanvullende aansprakelijkheid hebt aanvaard.

SECURITY.rst

@@ -0,0 +1,66 @@
+.. _security:
+
+Open Producten's security policies
+==================================
+
+Open Producten's development team is strongly committed to responsible reporting
+and disclosure of security-related issues. As such, we’ve adopted and follow a
+set of policies which conform to that ideal and are geared toward allowing us to
+deliver timely security updates to the official distribution of Open Producten.
+
+Reporting security issues
+-------------------------
+
+**Short version: please report security issues by emailing [email protected].**
+
+If you discover security issues in Open Producten or related projects under the same
+organization, we request you to disclose these in a *responsible* way by e-mailing to
+[email protected].
+
+It is extremely useful if you have a reproducible test case and/or clear steps on how to
+reproduce the vulnerability.
+
+Please do not report security issues on the public Github issue tracker, as this makes
+it visible which exploits exist before a fix is available, potentially comprising a lot
+of unprotected instances.
+
+Once you’ve submitted an issue via email, you should receive an acknowledgment from a
+member of the security team as soon as possible, and depending on the action to be taken,
+you may receive further followup emails.
+
+Timeline of the process
+-----------------------
+
+Open Producten has a technical steering group, of which all members are involved in the
+handling of security issues.
+
+1. The recipients of the report first validate if there is indeed a (possible) issue.
+
+2. After validation, we confirm that we received the report and if it is indeed a valid issue.
+
+3. We have a private Github repository accessible to the technical steering group. In this
+   repository, an issue is created for the vulnerability where the impact and possible
+   solutions are discussed.
+
+4. The next step is to create a (draft) Github security advisory, which is only visible
+   to the repository administrators and technical steering group. Severity and impact
+   will be established here.
+
+5. If appropriate, we request a `CVE identifier`_ from Github.
+
+6. A patch is implemented, reviewed and tested in a private fork.
+
+7. During the patch development process, known service providers are contacted to
+   inform them of the vulnerability and coordinate the release date and rollout of the
+   fix. Service providers should subscribe to the release early notice list.
+
+8. When the fix is tested and release coordination is done, the fix is merged into the
+   primary repository. The security advisory and release are published. Service providers
+   update their managed instances.
+
+9. The release and security vulnerability are communicated to the community. This
+   includes announcements on the Common Ground Slack and on `commonground.nl`_.
+
+
+.. _CVE identifier: https://cve.mitre.org/cve/identifiers/
+.. _commonground.nl: https://commonground.nl

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api/index.rst

@@ -0,0 +1,18 @@
+.. _api_index:
+
+==================
+API-specifications
+==================
+
+.. TODO: standard date
+
+Open Producten provides two API, one for **Product**'s and one for **Producttype**'s.
+Both of these API's are to be a recommended standard as of ..... The
+specifications can be found below.
+
+======================  ==========================================
+API                     Specification version(s)
+======================  ==========================================
+Product API             `0.0.2 <https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/maykinmedia/open-producten/v0.0.2/src/producten-openapi.yaml>`__
+Producttype API         `0.0.2 <https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/maykinmedia/open-producten/v0.0.2/src/producttypen-openapi.yaml>`__
+======================  ==========================================

docs/check_sphinx.py

@@ -0,0 +1,17 @@
+import subprocess
+
+
+def test_linkcheck(tmpdir):
+    doctrees = tmpdir.join("doctrees")
+    htmldir = tmpdir.join("html")
+    subprocess.check_call(
+        ["sphinx-build", "-W", "-blinkcheck", "-d", str(doctrees), ".", str(htmldir)],
+    )
+
+
+def test_build_docs(tmpdir):
+    doctrees = tmpdir.join("doctrees")
+    htmldir = tmpdir.join("html")
+    subprocess.check_call(
+        ["sphinx-build", "-W", "-bhtml", "-d", str(doctrees), ".", str(htmldir)],
+    )

docs/client-development/authentication.rst

@@ -0,0 +1,19 @@
+.. _client-development-auth:
+
+Authentication and authorization
+================================
+
+Open Producten uses the described authentication and authorization mechanism based on
+API tokens. It does not implement its own mechanism but uses `TokenAuthentication`_
+provided by `Django REST Framework`_.
+
+To connect to Open Producten, you have received a token key which should be included
+in your request's HTTP headers:
+
+.. code-block:: none
+
+   Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
+
+
+.. _TokenAuthentication: https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication
+.. _Django REST Framework: https://www.django-rest-framework.org/

docs/client-development/cors.rst

@@ -0,0 +1,39 @@
+.. _client-development-cors:
+
+Cross-Origin Resource Sharing (CORS)
+====================================
+
+Some clients develop against Open Producten using single-page-application technology that
+runs completely in the browser, such as React, Angular or other frameworks.
+
+Open Producten must be deployed with an appropriate CORS-configuration for this.
+
+.. note:: We always recommend using an API gateway/own backend to communicate with Open
+   Zaak. It's simpler because you don't have to deal with CORS, and there's less risk
+   of credentials/secrets leaking. You should **never** store client ID/secret in your
+   dist bundle(s).
+
+Production-grade settings
+-------------------------
+
+In production-like environments, we recommend using an explicit allow-list for the
+trusted origins. This requires deploying Open Producten with
+``CORS_ALLOWED_ORIGINS=https://my-app.example.com``, where ``https://my-app.example.com``
+is the domain where the application is deployed.
+
+Development/experimental configuration
+--------------------------------------
+
+If you're running Open Producten locally or on an environment with dummy data for
+development purposes, you can grant CORS access to every possible client using
+``CORS_ALLOW_ALL_ORIGINS=True`` in the Open Producten deployment.
+
+Separation of administrative interface and API
+----------------------------------------------
+
+The administrative interface authenticates using session cookies, while the APIs use
+the ``Authorization`` header with tokens.
+
+The session cookies are never sent on cross-domain requests, and the CORS configuration
+is configured to not allow credentials (which are typically session cookies). The API
+with the ``Authorization`` header is not affected by this policy.

docs/client-development/index.rst

@@ -0,0 +1,16 @@
+.. _client-development:
+
+Open Producten client documentation
+==============================
+
+Open Producten is primarily a provider of API's to be consumed by clients. If you're
+developing such a client (or consumer), you're in the right place!
+
+Please select your relevant topic
+
+.. toctree::
+   :maxdepth: 2
+
+   authentication
+   cors
+   recipes

docs/client-development/recipes.rst

@@ -0,0 +1,13 @@
+.. _client-development-recipes:
+
+Recipes
+=======
+
+In the recipes documentation, we aim to describe some patterns to organize your API
+calls to maximize performance.
+
+If you can give the equivalent example in your own language-of-preference, please
+submit a pull request!
+
+
+ .. TODO: include common patterns of how Open Producten will be used