From 2ce02ab419a67922f58f3d0e3aadbd171e3e6876 Mon Sep 17 00:00:00 2001
From: Steven Bal <steven@maykinmedia.nl>
Date: Tue, 23 Jul 2024 14:35:58 +0200
Subject: [PATCH] :memo: [open-zaak/open-zaak#1649] Documentation for
 documentation generation

---
 docs/index.rst      |  1 +
 docs/quickstart.rst | 64 +++++++++++++++++++++++++++++++++++++++++++++
 docs/reference.rst  | 11 ++++++++
 3 files changed, 76 insertions(+)
 create mode 100644 docs/reference.rst

diff --git a/docs/index.rst b/docs/index.rst
index 7d10b51..20dbb44 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -23,6 +23,7 @@ Features
    :caption: Contents:
 
    quickstart
+   reference
 
 
 
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index e6c9faf..f9407a0 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -38,5 +38,69 @@ Then you can initialize sentry by adding the following line to ``base.py``:
 After that, compare the settings from `open_api_framework.conf.base`_ to the settings
 defined in the project's ``base.py`` and remove settings from the latter to make use of the generic settings (if this is desired).
 
+Documenting environment variables
+---------------------------------
+
+This library provides utilities and a management command to generate .rst style documentation for environment variables that are
+in your project. The :func:`open_api_framework.conf.utils.config` can be used for this as follows to
+specify environment variable documentation. By default, all environment variables are added
+to the documentation (unless ``add_to_docs=False`` is passed to ``config``).
+
+.. code:: python
+
+    from open_api_framework.conf.base import *  # noqa
+    from open_api_framework.conf.utils import config
+
+    config(
+        "DB_NAME",
+        PROJECT_DIRNAME,
+        group="Database",
+        help_text="name of the PostgreSQL database.",
+    )
+
+The generic base settings are documented in the same way, so these will be automatically picked up
+when generating the documentation. In order to generate the documentation, the run the following command:
+
+.. code:: bash
+
+    python src/manage.py generate_envvar_docs --file docs/installation/config.rst
+
+If no ``--file`` is supplied, it will write to ``docs/env_config.rst``.
+Additionally, if some groups do not apply for your project, they can be excluded from the docs like this:
+
+.. code:: bash
+
+    python src/manage.py generate_envvar_docs --exclude-group Celery --exclude-group Cross-Origin-Resource-Sharing
+
+In order to add extra information for your project, add a template in ``templates/open_api_framework/env_config.rst`` and customize it:
+
+.. code:: html
+
+    {% extends "open_api_framework/env_config.rst" %}
+
+    {% block intro %}
+    Intro
+    -----
+
+    <some introductory information>
+
+    {% endblock %}
+
+    {% block extra %}
+
+    Custom section
+    --------------
+
+    <some extra information>
+
+    {% endblock %}
+
+
+
+.. note::
+
+    Currently only environment variables that are part of settings or modules that are loaded
+    when running management commands are included in the documentation
+
 
 .. _open_api_framework.conf.base: https://github.com/maykinmedia/open-api-framework/blob/main/open_api_framework/conf/base.py
diff --git a/docs/reference.rst b/docs/reference.rst
new file mode 100644
index 0000000..d5505fc
--- /dev/null
+++ b/docs/reference.rst
@@ -0,0 +1,11 @@
+=========
+Reference
+=========
+
+Public API documentation.
+
+Utilities
+=========
+
+.. automodule:: open_api_framework.conf.utils
+    :members: