From 6056677f35347cd82c12fc9020b02ef142dbe289 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 16 Mar 2018 16:53:37 +0000 Subject: [PATCH] sphinxext: Start parsing 'Opt.help' 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: Ic6c2dcbe7823dd3fdc71db8dc5afab2d604559e3 Closes-Bug: #1755783 (cherry picked from commit 03ff144f0bf386982d379d18aeb9183146a05fd5) --- oslo_config/sphinxext.py | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/oslo_config/sphinxext.py b/oslo_config/sphinxext.py index 34a1ef08..43517939 100644 --- a/oslo_config/sphinxext.py +++ b/oslo_config/sphinxext.py @@ -20,6 +20,7 @@ from sphinx.directives import ObjectDescription from sphinx.domains import Domain from sphinx.domains import ObjType from sphinx.roles import XRefRole +from sphinx.util import logging from sphinx.util.nodes import make_refnode from sphinx.util.nodes import nested_parse_with_titles @@ -53,7 +54,7 @@ def _list_table(headers, data, title='', columns=None): def _indent(text, n=2): padding = ' ' * n - return '\n'.join(padding + l for l in text.splitlines()) + return '\n'.join(padding + l if l else l for l in text.splitlines()) def _make_anchor_target(group_name, option_name): @@ -98,8 +99,9 @@ def _format_opt(opt, group_name): yield _indent(':Type: %s' % opt_type) for default in generator._format_defaults(opt): if default: - default = '``' + default + '``' - yield _indent(':Default: %s' % default) + yield _indent(':Default: ``%s``' % default) + else: + yield _indent(':Default: ``%r``' % default) if getattr(opt.type, 'min', None) is not None: yield _indent(':Minimum Value: %s' % opt.type.min) if getattr(opt.type, 'max', None) is not None: @@ -148,7 +150,8 @@ def _format_opt(opt, group_name): help_text = opt.help if help_text: yield '' - yield _indent(help_text.strip()) + for line in help_text.strip().splitlines(): + yield _indent(line.rstrip()) # We don't bother outputting this if not using new-style choices with # inline descriptions @@ -183,8 +186,10 @@ def _format_opt(opt, group_name): yield _indent(' Its value may be silently ignored ') yield _indent(' in the future.') if opt.deprecated_reason: + reason = ' '.join([x.strip() for x in + opt.deprecated_reason.splitlines()]) yield '' - yield _indent(' :Reason: ' + opt.deprecated_reason) + yield _indent(' :Reason: ' + reason) yield '' @@ -307,7 +312,14 @@ class ShowOptionsDirective(rst.Directive): node = nodes.section() node.document = self.state.document - nested_parse_with_titles(self.state, result, node) + + # With the resolution for bug #1755783, we now parse the 'Opt.help' + # 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