Skip to content

Commit 45515f8

Browse files
zopieuxzopieux
committed
Added a REsT directive to generate the setting definition list.
The directive can be rendered as a table or a definition list. I wrote a short description of each setting.
1 parent 060022f commit 45515f8

File tree

4 files changed

+170
-5
lines changed

4 files changed

+170
-5
lines changed

‎docs/advanced_topics.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,8 @@ That's all, now Django OAuth Toolkit will use your model wherever an Application
5050
See issue #90 (https://github.com/evonove/django-oauth-toolkit/issues/90) for details
5151

5252

53+
.. _skip-auth-form:
54+
5355
Skip authorization form
5456
=======================
5557

‎docs/conf.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@
1818
# documentation root, use os.path.abspath to make it absolute, like shown here.
1919
here = os.path.abspath(os.path.dirname(__file__))
2020
sys.path.insert(0, here)
21-
sys.path.insert(0, os.path.join(here, '..'))
22-
sys.path.insert(0, os.path.join(here, '..', 'example'))
21+
sys.path.insert(0, os.path.dirname(here))
22+
sys.path.insert(0, os.path.join(os.path.dirname(here), 'example'))
2323

2424
os.environ['DJANGO_SETTINGS_MODULE'] = 'example.settings.dev'
2525
import oauth2_provider
@@ -31,7 +31,7 @@
3131

3232
# Add any Sphinx extension module names here, as strings. They can be extensions
3333
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
34-
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'rfc']
34+
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'rfc', 'settings_generator']
3535

3636
# Add any paths that contain templates here, relative to this directory.
3737
templates_path = ['_templates']

‎docs/settings.rst

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,11 @@ For example:
2020
}
2121
2222
23-
TODO: add reference documentation for DOT settings
23+
A big *thank you* to the guys from Django REST Framework for inspiring this.
2424

25-
A big *thank you* to the guys from Django REST Framework for inspiring this.
25+
26+
List of available settings
27+
--------------------------
28+
29+
.. settings_generator::
30+
:type: definitions

‎docs/settings_generator.py

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
"""
2+
Custom Sphinx documentation module to generate the table of all settings.
3+
"""
4+
5+
6+
DESCRIPTIONS = {
7+
'ACCESS_TOKEN_EXPIRE_SECONDS': """
8+
The number of seconds an access token remains valid. Requesting a protected
9+
resource after this duration will fail. Keep this value high enough so clients
10+
can cache the token for a reasonable amount of time.
11+
""",
12+
'APPLICATION_MODEL': """
13+
The import string of the class (model) representing your applications. Overwrite
14+
this value if you wrote your own implementation (subclass of
15+
``oauth2_provider.models.Application``).
16+
""",
17+
'AUTHORIZATION_CODE_EXPIRE_SECONDS': """
18+
The number of seconds an authorization code remains valid. Requesting an access
19+
token after this duration will fail. :rfc:`4.1.2` recommends a
20+
10 minutes (600 seconds) duration.
21+
""",
22+
'CLIENT_ID_GENERATOR_CLASS': """
23+
The import string of the class responsible for generating client identifiers.
24+
These are usually random strings.
25+
""",
26+
'CLIENT_SECRET_GENERATOR_CLASS': """
27+
The import string of the class responsible for generating client secrets.
28+
These are usually random strings.
29+
""",
30+
'CLIENT_SECRET_GENERATOR_LENGTH': """
31+
The length of the generated secrets, in characters. If this value is too low,
32+
secrets may become subject to bruteforce guessing.
33+
""",
34+
'OAUTH2_VALIDATOR_CLASS': """
35+
The import string of the ``oauthlib.oauth2.RequestValidator`` subclass that
36+
validates every step of the OAuth2 process.
37+
""",
38+
'READ_SCOPE': """
39+
The name of the *read* scope.
40+
""",
41+
'REQUEST_APPROVAL_PROMPT': """
42+
Can be ``'force'`` or ``'auto'``.
43+
The strategy used to display the authorization form. Refer to :ref:`skip-auth-form`.
44+
""",
45+
'SCOPES': """
46+
A dictionnary mapping each scope name to its human description.
47+
""",
48+
'WRITE_SCOPE': """
49+
The name of the *write* scope.
50+
""",
51+
}
52+
53+
54+
from docutils import nodes
55+
from docutils.parsers.rst import Directive, directives
56+
from docutils.utils import SystemMessagePropagation
57+
58+
59+
def _type_choice(argument):
60+
return directives.choice(argument, ('table', 'definitions'))
61+
62+
63+
class SettingsGenerator(Directive):
64+
"""Generate the settings table/definition list."""
65+
66+
required_arguments = 0
67+
optional_arguments = 0
68+
final_argument_whitespace = True
69+
option_spec = {'type': _type_choice}
70+
has_content = True
71+
node_class = None
72+
73+
_headers = ("Name", "Can be empty", "Description")
74+
_headers_size = (1, 1, 6)
75+
76+
def _build_definition_list(self, defaults):
77+
from oauth2_provider import settings
78+
79+
items = []
80+
for setting, default_value in defaults:
81+
text_nodes, messages = self.state.inline_text(DESCRIPTIONS.get(setting, "TODO").strip(), self.lineno)
82+
node_name = nodes.literal(text=setting)
83+
node_default = nodes.paragraph(text="Default value: ")
84+
node_default += nodes.literal(text=repr(default_value))
85+
node_description = nodes.paragraph()
86+
node_description.extend(text_nodes)
87+
subitems = [node_default, node_description]
88+
89+
if setting in settings.MANDATORY:
90+
notice = nodes.paragraph()
91+
notice += nodes.strong(text="The value cannot be empty.")
92+
subitems.append(notice)
93+
94+
term = nodes.term()
95+
term += node_name
96+
items.append(nodes.definition_list_item('', term, nodes.definition('', *subitems)))
97+
98+
deflist = nodes.definition_list('', *items)
99+
return [deflist]
100+
101+
def _build_table(self, defaults):
102+
from oauth2_provider import settings
103+
104+
table = nodes.table()
105+
tgroup = nodes.tgroup(cols=len(self._headers))
106+
table += tgroup
107+
for factor in self._headers_size:
108+
colspec = nodes.colspec(colwidth=factor)
109+
tgroup += colspec
110+
111+
tbody = nodes.tbody()
112+
for setting, default_value in defaults:
113+
text_nodes, messages = self.state.inline_text(DESCRIPTIONS.get(setting, "TODO").strip(), self.lineno)
114+
node_name = nodes.paragraph()
115+
node_name += nodes.literal(text=setting)
116+
node_default = nodes.paragraph(text="Default value: ")
117+
node_default += nodes.literal(text=repr(default_value))
118+
node_empty = nodes.paragraph(text="No" if setting in settings.MANDATORY else "Yes")
119+
node_description = nodes.paragraph()
120+
node_description.extend(text_nodes)
121+
cells = [[node_name, node_default], [node_empty], [node_description]]
122+
row_node = nodes.row()
123+
for cell in cells:
124+
row_node += nodes.entry('', *cell)
125+
tbody += row_node
126+
127+
thead = nodes.thead()
128+
thead_row = nodes.row()
129+
for head in self._headers:
130+
entry = nodes.entry(head, nodes.paragraph(text=head))
131+
thead_row += entry
132+
thead += thead_row
133+
tgroup += thead
134+
tgroup += tbody
135+
return [table]
136+
137+
def run(self):
138+
from oauth2_provider import settings
139+
defaults = sorted([(k, v) for k, v in settings.DEFAULTS.items() if not k.startswith('_')])
140+
141+
opt_type = self.options.get('type')
142+
if opt_type == 'table':
143+
return self._build_table(defaults)
144+
elif opt_type == 'definitions':
145+
return self._build_definition_list(defaults)
146+
else:
147+
error = self.state_machine.reporter.error("type must be 'table' or 'definitions'")
148+
raise SystemMessagePropagation(error)
149+
150+
151+
def setup(app):
152+
"""
153+
Install the plugin.
154+
155+
:param app: Sphinx application context.
156+
"""
157+
app.add_directive('settings_generator', SettingsGenerator)
158+
return

0 commit comments

Comments
 (0)