@@ -38,5 +38,69 @@ Then you can initialize sentry by adding the following line to ``base.py``:
38
38
After that, compare the settings from `open_api_framework.conf.base `_ to the settings
39
39
defined in the project's ``base.py `` and remove settings from the latter to make use of the generic settings (if this is desired).
40
40
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
+
41
105
42
106
.. _open_api_framework.conf.base : https://github.com/maykinmedia/open-api-framework/blob/main/open_api_framework/conf/base.py
0 commit comments