summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorStephen Finucane <sfinucan@redhat.com>2018-08-21 14:57:13 +0100
committerStephen Finucane <sfinucan@redhat.com>2018-08-22 11:17:06 +0100
commit6fc8c8287a178cedbeb42e256f60f3bcaa66e195 (patch)
tree6f1cbdbdaa287b4c848cb5dbc2ab2622763aba39
parent055e5f437af3ed49540b9b713bdb5d4c1ad650fd (diff)
downloadoslo-policy-6fc8c8287a178cedbeb42e256f60f3bcaa66e195.tar.gz
sphinxext: Start parsing 'DocumentedRuleDefault.description' as rST
Users expect this to be parsed as rST and write their docstrings accordingly. This has the potential to introduce warnings for users with improperly formatted rST and these warnings can be promoted to errors if 'sphinx-build' is used with the '-W' option. As a result, we disable the 'warning-is-error' logger for these options. We may wish to change this behavior in the future. It is not really possible to test this yet as the output wouldn't look much different. In addition, the error messages generated are rather unhelpful. Both of these can be changed in a future modification. Change-Id: I4572eef31a8675eabb791c14279490348e949cd0 Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
-rw-r--r--oslo_policy/sphinxext.py19
1 files changed, 13 insertions, 6 deletions
diff --git a/oslo_policy/sphinxext.py b/oslo_policy/sphinxext.py
index c5c8897..d8b8ce0 100644
--- a/oslo_policy/sphinxext.py
+++ b/oslo_policy/sphinxext.py
@@ -21,6 +21,7 @@ from docutils.parsers import rst
from docutils.parsers.rst import directives
from docutils import statemachine
from oslo_config import cfg
+from sphinx.util import logging
from sphinx.util.nodes import nested_parse_with_titles
from oslo_policy import generator
@@ -40,7 +41,7 @@ def _indent(text):
def _format_policy_rule(rule):
"""Output a definition list-style rule.
- For example:
+ For example::
``os_compute_api:servers:create``
:Default: ``rule:admin_or_owner``
@@ -70,10 +71,8 @@ def _format_policy_rule(rule):
yield ''
if rule.description:
- for line in statemachine.string2lines(
- rule.description, tab_width=4, convert_whitespace=True):
- if line:
- yield _indent(line)
+ for line in rule.description.strip().splitlines():
+ yield _indent(line.rstrip())
else:
yield _indent('(no description provided)')
@@ -151,7 +150,15 @@ class ShowPolicyDirective(rst.Directive):
node = nodes.section()
node.document = self.state.document
- nested_parse_with_titles(self.state, result, node)
+
+ # 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