Merge pull request #22 from maykinmedia/feature/autodoc

✨ [open-zaak/open-zaak#1649] Command to document envvars

Author: stevenbal

MANIFEST.in

@@ -2,6 +2,7 @@ include *.rst
 include LICENSE
 include open_api_framework/py.typed
 recursive-include open_api_framework *.html
+recursive-include open_api_framework *.rst
 recursive-include open_api_framework *.txt
 recursive-include open_api_framework *.po
 recursive-include open_api_framework/static *.css

docs/index.rst

@@ -23,6 +23,7 @@ Features
    :caption: Contents:
 
    quickstart
+   reference
 
 
 

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

docs/reference.rst

@@ -0,0 +1,11 @@
+=========
+Reference
+=========
+
+Public API documentation.
+
+Utilities
+=========
+
+.. automodule:: open_api_framework.conf.utils
+    :members: