Merge pull request #147 from open-zaak/feature/more-docs

Added more documentation structure

README.rst

@@ -31,7 +31,10 @@ De gegevens worden ontsloten middels een `set API's`_, te weten:
 * Documenten API (`Documenten API-specificatie 1.0 RC`_)
 * Catalogi API (`Catalogi API-specificatie 1.0 RC`_)
 * Besluiten API (`Besluiten API-specificatie 1.0 RC`_)
-* Autorisatie API (`Autorisaties API-specificatie 1.0 RC`_)
+* Autorisaties API (`Autorisaties API-specificatie 1.0 RC`_)
+
+De `Notificaties API`_ is nodig voor **Open Zaak** en is beschikbaar via
+`Open Notificaties`_.
 
 .. _`Common Ground`: https://commonground.nl/
 .. _`zaakgericht werken`: https://www.vngrealisatie.nl/ondersteuningsmiddelen/zaakgericht-werken
@@ -41,12 +44,15 @@ De gegevens worden ontsloten middels een `set API's`_, te weten:
 .. _`Catalogi API-specificatie 1.0 RC`: https://zaakgerichtwerken.vng.cloud/standaard/catalogi/index
 .. _`Besluiten API-specificatie 1.0 RC`: https://zaakgerichtwerken.vng.cloud/standaard/besluiten/index
 .. _`Autorisaties API-specificatie 1.0 RC`: https://zaakgerichtwerken.vng.cloud/standaard/autorisaties/index
+.. _`Notificaties API`: https://zaakgerichtwerken.vng.cloud/standaard/notificaties/index
+.. _`Open Notificaties`: https://github.com/open-zaak/open-notificaties
 
 **Open Zaak** gebruikt de code van de
 `referentie implementaties van VNG Realisatie`_ als basis om een stabiele set
 API's te realiseren die in productie gebruikt kunnen worden bij gemeenten.
 
 .. _`referentie implementaties van VNG Realisatie`: https://github.com/VNG-Realisatie/gemma-zaken
+.. _`Documentatie`: https://open-zaak.readthedocs.io/en/latest/
 
 Licentie
 ========

docs/api/index.rst

@@ -0,0 +1,38 @@
+.. _api_index:
+
+==================
+API-specifications
+==================
+
+Open Zaak adheres to the API-specifications as described by the `VNG standards
+for "API's voor Zaakgericht werken"`_. The interaction between these API's can
+be found there as well.
+
+.. _`VNG standards for "API's voor Zaakgericht werken"`: https://zaakgerichtwerken.vng.cloud/
+
+Supported API versions
+======================
+
+The following API's are available in Open Zaak:
+
+======================  ==========================================
+API                     Specification version(s)
+======================  ==========================================
+`Zaken API`_            `1.0 <https://zaken-api.vng.cloud/api/v1/schema/>`__
+`Documenten API`_       `1.0 <https://documenten-api.vng.cloud/api/v1/schema/>`__
+`Catalogi API`_         `1.0 <https://catalogi-api.vng.cloud/api/v1/schema/>`__
+`Besluiten API`_        `1.0 <https://besluiten-api.vng.cloud/api/v1/schema/>`__
+`Autorisaties API`_     `1.0 <https://autorisaties-api.vng.cloud/api/v1/schema/>`__
+======================  ==========================================
+
+.. _`Zaken API`: https://zaakgerichtwerken.vng.cloud/standaard/zaken/index
+.. _`Documenten API`: https://zaakgerichtwerken.vng.cloud/standaard/documenten/index
+.. _`Catalogi API`: https://zaakgerichtwerken.vng.cloud/standaard/catalogi/index
+.. _`Besluiten API`: https://zaakgerichtwerken.vng.cloud/standaard/besluiten/index
+.. _`Autorisaties API`: https://zaakgerichtwerken.vng.cloud/standaard/autorisaties/index
+
+In addition, Open Zaak requires access to a `Notificaties API`_. Open Zaak uses
+`Open Notificaties`_ by default.
+
+.. _`Notificaties API`: https://zaakgerichtwerken.vng.cloud/standaard/notificaties/index
+.. _`Open Notificaties`: https://github.com/open-zaak/open-notificaties

docs/conf.py

@@ -50,7 +50,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_logo = "logo.png"
+html_logo = "logo.svg"
 html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/development/contributing.rst

@@ -0,0 +1,4 @@
+.. _development_contributing:
+
+Contributing
+============

docs/development/development-environment.rst

@@ -0,0 +1,4 @@
+.. _development_development-environment:
+
+Development environment
+=======================

docs/development/index.rst

@@ -0,0 +1,12 @@
+.. _development_index:
+
+Development (TODO)
+==================
+
+Open Zaak is open-source software. We’d love to have you contribute!
+
+.. toctree::
+   :maxdepth: 2
+
+   contributing
+   development-environment

docs/index.rst

@@ -1,30 +1,40 @@
-.. Open zaak documentation master file, created by
-   sphinx-quickstart on Thu Oct 10 14:19:20 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+Open Zaak Documentation
+=======================
 
-Welcome to Open zaak's documentation!
-=====================================
+**Open Zaak** is a modern, open-source data- and services-layer to enable
+`zaakgericht werken`_, a Dutch alternative to case management. Open Zaak offers
+structured data storage and services that implement the `VNG standards for
+"API's voor Zaakgericht werken"`_ in line with the `Common Ground`_ model.
 
-.. toctree::
-   :maxdepth: 3
-   :caption: Contents:
-
-   deployment/linux
-   deployment/containers
+.. _`Common Ground`: https://commonground.nl/
+.. _`zaakgericht werken`: https://www.vngrealisatie.nl/ondersteuningsmiddelen/zaakgericht-werken
+.. _`VNG standards for "API's voor Zaakgericht werken"`: https://zaakgerichtwerken.vng.cloud/
 
+Getting Started
+---------------
 
-TODO
-====
+To get you started, you might find some of these links relevant:
 
-This documentation is work in progress.
+* New to Open Zaak? Have a look at the :ref:`introduction_index`
+* New to the VNG standards for "API's voor Zaakgericht werken"? Read up on the
+  :ref:`api_index`.
+* Want to get started with Open Zaak yourself? See :ref:`installation_index`.
+* Want to configure or manage data in Open Zaak? Read the :ref:`manual_index`.
+* Need help with Open Zaak? Contact :ref:`support_index`.
+* Are you a developer? Head over to :ref:`development_index`!
 
-.. todolist::
+Open Zaak `is`_ and only uses :ref:`introduction_open-source`.
 
+.. _`is`: https://github.com/open-zaak/open-zaak/blob/master/LICENSE.md
+.. _`open-source`: introduction/open-source
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+
+   introduction/index
+   api/index
+   installation/index
+   manual/index
+   support/index
+   development/index

docs/deployment/linux.rst → docs/installation/deployment/linux.rst

@@ -31,7 +31,7 @@ Software requirements
 At least the following software must be present on the server system:
 
 * Python 3.7 (with virtualenv, which is present by default).
-* A PostgreSQL database server (at least version 10) with Postgis enabled. You
+* A PostgreSQL database server (at least version 10) with PostGIS enabled. You
   can make use of a remote database or run it on the same server.
 * Redis as message broker and cache. May be on the same machine, or a remote
   service.

docs/installation/hardware.rst

@@ -0,0 +1,4 @@
+.. _installation_hardware:
+
+Hardware requirements
+=====================

docs/installation/index.rst

@@ -0,0 +1,14 @@
+.. _installation_index:
+
+Installation
+============
+
+There are several ways to install Open Zaak.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   hardware
+   deployment/linux
+   deployment/containers

docs/introduction/architecture.rst

@@ -0,0 +1,37 @@
+Architecture
+============
+
+**Open Zaak** is based on the `reference implementation of the "API's voor
+Zaakgericht werken"`_ made by `VNG Realisatie`_. The overall architecture
+remains faithful to the `Common Ground`_ principles and all API specifications.
+
+The architecture of **Open Zaak** focusses on excellent performance, optimal
+stability and to guarantee data integrity.
+
+To that end, **Open Zaak** combines the "API's voor Zaakgericht werken" that
+are essentially tightly coupled, into a single product. This allows for major
+performance improvements since related objects (like a `BESLUIT` for a `ZAAK`)
+do not need to fetched over the network but can be directly obtained from the
+database. This also guarantees data integrity on database level, rather than on
+service (API) level.
+
+In addition, **Open Zaak** uses caching wherever possible to prevent needless
+requests over the netwerk to fetch data from external API's. Data integrity can
+not be guaranteed on database level when relations are created to external
+API's. In this case, data integrity is enforced on service level as much as
+possible.
+
+The use of external API's is fully supported in **Open Zaak**, even for API's
+that are also offered by **Open Zaak** itself. For example, a `ZAAK` in
+**Open Zaak**, available via the `Zaken API` can have a `DOCUMENT` that is
+accessible via an external `Documenten API` from another vendor. The only
+requirement is that all API's adhere to `VNG standards for "API's voor
+Zaakgericht werken"`_.
+
+No permanent copies are made of original sources in **Open Zaak** as dictated
+by the `Common Ground`_ principles.
+
+.. _reference implementation of the "API's voor Zaakgericht werken": https://github.com/VNG-Realisatie/gemma-zaken
+.. _VNG Realisatie: https://www.vngrealisatie.nl/
+.. _Common Ground: https://commonground.nl/
+.. _`VNG standards for "API's voor Zaakgericht werken"`: https://zaakgerichtwerken.vng.cloud/

docs/introduction/index.rst

@@ -0,0 +1,42 @@
+.. _introduction_index:
+
+Introduction
+============
+
+**Open Zaak** is a modern, open-source data- and services-layer to enable
+`zaakgericht werken`_, a Dutch alternative to case management. Open Zaak offers
+structured data storage and services that implement the `VNG standards for
+"API's voor Zaakgericht werken"`_ in line with the `Common Ground`_ model.
+
+.. _`Common Ground`: https://commonground.nl/
+.. _`zaakgericht werken`: https://www.vngrealisatie.nl/ondersteuningsmiddelen/zaakgericht-werken
+.. _`VNG standards for "API's voor Zaakgericht werken"`: https://zaakgerichtwerken.vng.cloud/
+
+Open Zaak exposes several :ref:`API's<api_index>` to store and retrieve data:
+
+* Zaken API (case instances)
+* Documenten API (documents)
+* Catalogi API (case types)
+* Besluiten API (decisions)
+* Autorisaties API (authorizations)
+
+The `Notificaties API`_ is required for Open Zaak to work but is available as
+a seperate package, `Open Notificaties`_.
+
+.. _`Notificaties API`: https://zaakgerichtwerken.vng.cloud/standaard/notificaties/index
+.. _`Open Notificaties`: https://github.com/open-zaak/open-notificaties
+
+**Open Zaak** is based on the `API reference implementations by VNG Realisatie`_
+to create a production-grade product that can be used by municipalities.
+
+.. _`API reference implementations by VNG Realisatie`: https://github.com/VNG-Realisatie/gemma-zaken
+.. _`Documentatie`: https://open-zaak.readthedocs.io/en/latest/
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Further reading
+
+   architecture
+   performance/scenarios
+   open-source

docs/introduction/open-source.rst

@@ -0,0 +1,8 @@
+.. _introduction_open-source:
+
+Open-source (TODO)
+==================
+
+Open Zaak is open-source and available under the EUPL license.
+
+In addition, Open Zaak makes use of various open-source libraries: