Skip to content

Commit 9194e18

Browse files
authored
Merge pull request #22 from maykinmedia/feature/autodoc
✨ [open-zaak/open-zaak#1649] Command to document envvars
2 parents a965065 + 2867cb7 commit 9194e18

File tree

14 files changed

+688
-52
lines changed

14 files changed

+688
-52
lines changed

MANIFEST.in

+1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ include *.rst
22
include LICENSE
33
include open_api_framework/py.typed
44
recursive-include open_api_framework *.html
5+
recursive-include open_api_framework *.rst
56
recursive-include open_api_framework *.txt
67
recursive-include open_api_framework *.po
78
recursive-include open_api_framework/static *.css

docs/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Features
2323
:caption: Contents:
2424

2525
quickstart
26+
reference
2627

2728

2829

docs/quickstart.rst

+64
Original file line numberDiff line numberDiff line change
@@ -38,5 +38,69 @@ Then you can initialize sentry by adding the following line to ``base.py``:
3838
After that, compare the settings from `open_api_framework.conf.base`_ to the settings
3939
defined in the project's ``base.py`` and remove settings from the latter to make use of the generic settings (if this is desired).
4040

41+
Documenting environment variables
42+
---------------------------------
43+
44+
This library provides utilities and a management command to generate .rst style documentation for environment variables that are
45+
in your project. The :func:`open_api_framework.conf.utils.config` can be used for this as follows to
46+
specify environment variable documentation. By default, all environment variables are added
47+
to the documentation (unless ``add_to_docs=False`` is passed to ``config``).
48+
49+
.. code:: python
50+
51+
from open_api_framework.conf.base import * # noqa
52+
from open_api_framework.conf.utils import config
53+
54+
config(
55+
"DB_NAME",
56+
PROJECT_DIRNAME,
57+
group="Database",
58+
help_text="name of the PostgreSQL database.",
59+
)
60+
61+
The generic base settings are documented in the same way, so these will be automatically picked up
62+
when generating the documentation. In order to generate the documentation, the run the following command:
63+
64+
.. code:: bash
65+
66+
python src/manage.py generate_envvar_docs --file docs/installation/config.rst
67+
68+
If no ``--file`` is supplied, it will write to ``docs/env_config.rst``.
69+
Additionally, if some groups do not apply for your project, they can be excluded from the docs like this:
70+
71+
.. code:: bash
72+
73+
python src/manage.py generate_envvar_docs --exclude-group Celery --exclude-group Cross-Origin-Resource-Sharing
74+
75+
In order to add extra information for your project, add a template in ``templates/open_api_framework/env_config.rst`` and customize it:
76+
77+
.. code:: html
78+
79+
{% extends "open_api_framework/env_config.rst" %}
80+
81+
{% block intro %}
82+
Intro
83+
-----
84+
85+
<some introductory information>
86+
87+
{% endblock %}
88+
89+
{% block extra %}
90+
91+
Custom section
92+
--------------
93+
94+
<some extra information>
95+
96+
{% endblock %}
97+
98+
99+
100+
.. note::
101+
102+
Currently only environment variables that are part of settings or modules that are loaded
103+
when running management commands are included in the documentation
104+
41105

42106
.. _open_api_framework.conf.base: https://github.com/maykinmedia/open-api-framework/blob/main/open_api_framework/conf/base.py

docs/reference.rst

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
=========
2+
Reference
3+
=========
4+
5+
Public API documentation.
6+
7+
Utilities
8+
=========
9+
10+
.. automodule:: open_api_framework.conf.utils
11+
:members:

0 commit comments

Comments
 (0)