/usr/lib/python2.7/dist-packages/oslo_policy/sphinxext.py is in python-oslo.policy 1.33.1-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | # 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."""
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.util.nodes import nested_parse_with_titles
from oslo_policy import generator
def _indent(text):
"""Indent by four spaces."""
prefix = ' ' * 4
def prefixed_lines():
for line in text.splitlines(True):
yield (prefix + line if line.strip() else line)
return ''.join(prefixed_lines())
def _format_policy_rule(rule):
"""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 '``{}``'.format(rule.name)
if rule.check_str:
yield _indent(':Default: ``{}``'.format(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'])))
yield ''
if rule.description:
for line in statemachine.string2lines(
rule.description, tab_width=4, convert_whitespace=True):
if line:
yield _indent(line)
else:
yield _indent('(no description provided)')
yield ''
def _format_policy_section(section, rules):
# The nested_parse_with_titles will ensure the correct header leve is used.
yield section
yield '=' * len(section)
yield ''
for rule in rules:
for line in _format_policy_rule(rule):
yield line
def _format_policy(namespaces):
policies = generator.get_policies_dict(namespaces)
for section in sorted(policies.keys()):
for line in _format_policy_section(section, policies[section]):
yield line
class ShowPolicyDirective(rst.Directive):
has_content = False
option_spec = {
'config-file': directives.unchanged,
}
def run(self):
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 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(
'could not find config file in: %s' % str(candidates)
)
self.info('loading config file %s' % 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.ViewList()
source_name = '<' + __name__ + '>'
for line in _format_policy(namespaces):
result.append(line, source_name)
node = nodes.section()
node.document = self.state.document
nested_parse_with_titles(self.state, result, node)
return node.children
def setup(app):
app.add_directive('show-policy', ShowPolicyDirective)
|