Handle adjacent notes from doxygen more correctly

The Doxygen documentation seems to claim that adjacent @note entries
will be collapsed into a single "note" element, as separate paragraphs.
This seems to be reflected in the XML output: multiple <para> entries
in a single <simplesec kind="note"> with a <simplesecsep/> element
between them.

Our XML-to-RST converter gets the entire contents of the simplesec
element, parsed into a unicode string with a single newline between
paragraphs.  Paragraphs seem to always start with two spaces, though
I have not tracked down the origin of this behavior.  Prior to this
commit, we would just output this entire unicode string directly.
Since our template puts a tab character before the note string, this
means that the first paragraph is indented by a tab and two spaces,
and the second paragraph by just two spaces.  Sphinx warns about this,
as "block did not end with blank line; unexpected whitespace", and
the paragraphs are indented differently within the note.

Fix the warning by checking for newlines in the interior of the
parsed unicode string, and introducing the appropriate whitespace
for the Sphinx parser.

ticket: 7447
tags: pullup
target_version: 1.11

1 files changed, 2 insertions, 1 deletions

diff --git a/doc/tools/doxybuilder_funcs.py b/doc/tools/doxybuilder_funcs.py
index 13331f8bad..7e54750c8b 100644
--- a/doc/tools/doxybuilder_funcs.py
+++ b/doc/tools/doxybuilder_funcs.py
@@ -503,7 +503,8 @@ class DoxyFuncs(XML2AST):
     def return_notes_decorator(self, node, value):
         if node.name == 'simplesect':
             if node.attributes['kind'] == 'note':
-                return value
+                # We indent notes with an extra tab.  Do it for all paragraphs.
+                return value.replace("\n  ", "\n\n\t  ");
         else:
             return None