1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
# Copyright 2017 Red Hat, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""Sphinx extension for pretty-formatting policy docs."""
from collections.abc import Generator, Iterable, Sequence
import os
from docutils import nodes
from docutils.parsers import rst
from docutils.parsers.rst import directives
from docutils import statemachine
from oslo_config import cfg
from sphinx import application
from sphinx.util import logging
from sphinx.util.nodes import nested_parse_with_titles
from oslo_policy import generator
from oslo_policy import policy
def _indent(text: str) -> str:
"""Indent by four spaces."""
prefix = ' ' * 4
def prefixed_lines() -> Iterable[str]:
for line in text.splitlines(True):
yield (prefix + line if line.strip() else line)
return ''.join(prefixed_lines())
def _format_policy_rule(
rule: policy.RuleDefault,
) -> Generator[str, None, None]:
"""Output a definition list-style rule.
For example::
``os_compute_api:servers:create``
:Default: ``rule:admin_or_owner``
:Operations:
- **POST** ``/servers``
Create a server
"""
yield f'``{rule.name}``'
if rule.check_str:
yield _indent(f':Default: ``{rule.check_str}``')
else:
yield _indent(':Default: <empty string>')
if hasattr(rule, 'operations'):
yield _indent(':Operations:')
for operation in rule.operations:
yield _indent(
_indent(
'- **{}** ``{}``'.format(
operation['method'], operation['path']
)
)
)
if hasattr(rule, 'scope_types') and rule.scope_types is not None:
yield _indent(':Scope Types:')
for scope_type in rule.scope_types:
yield _indent(_indent(f'- **{scope_type}**'))
yield ''
if rule.description:
for line in rule.description.strip().splitlines():
yield _indent(line.rstrip())
else:
yield _indent('(no description provided)')
yield ''
def _format_policy_section(
section: str, rules: Sequence[policy.RuleDefault]
) -> Generator[str, None, None]:
# The nested_parse_with_titles will ensure the correct header leve is used.
yield section
yield '=' * len(section)
yield ''
for rule in rules:
yield from _format_policy_rule(rule)
def _format_policy(namespaces: Sequence[str]) -> Generator[str, None, None]:
policies = generator.get_policies_dict(namespaces)
for section in sorted(policies.keys()):
yield from _format_policy_section(section, policies[section])
class ShowPolicyDirective(rst.Directive):
has_content = False
option_spec = {
'config-file': directives.unchanged,
}
def run(self) -> list[nodes.Node]:
env = self.state.document.settings.env
app = env.app
config_file = self.options.get('config-file')
# if the config_file option was not defined, attempt to reuse the
# 'oslo_policy.sphinxpolicygen' extension's setting
if not config_file and hasattr(
env.config, 'policy_generator_config_file'
):
config_file = env.config.policy_generator_config_file
if not config_file:
raise ValueError('could not find config file')
# If we are given a file that isn't an absolute path, look for it
# in the source directory if it doesn't exist.
candidates = [
config_file,
os.path.join(
app.srcdir,
config_file,
),
]
for c in candidates:
if os.path.isfile(c):
config_path = c
break
else:
raise ValueError(
f'could not find config file in: {str(candidates)}'
)
self.info(f'loading config file {config_path}')
conf = cfg.ConfigOpts()
opts = generator.GENERATOR_OPTS + generator.RULE_OPTS
conf.register_cli_opts(opts)
conf.register_opts(opts)
conf(
args=['--config-file', config_path],
)
namespaces = conf.namespace[:]
result = statemachine.StringList()
source_name = '<' + __name__ + '>'
for line in _format_policy(namespaces):
result.append(line, source_name)
node = nodes.section()
node.document = self.state.document
# With the resolution for bug #1788183, we now parse the
# 'DocumentedRuleDefault.description' attribute as rST. Unfortunately,
# there are a lot of broken option descriptions out there and we don't
# want to break peoples' builds suddenly. As a result, we disable
# 'warning-is-error' temporarily. Users will still see the warnings but
# the build will continue.
with logging.skip_warningiserror():
nested_parse_with_titles(self.state, result, node)
return node.children
def setup(app: application.Sphinx) -> dict[str, bool]:
app.add_directive('show-policy', ShowPolicyDirective)
return {
'parallel_read_safe': True,
'parallel_write_safe': True,
}
|
