Ensure empty line before code and math blocks in doxygen pydoc

Sphinx requires an empty line before code and math blocks, whereas
doxygen does not.  This update ensures that a blank line is included
before generated code and math blocks in the pydoc output.  This is
done by post-processing the docstring line by line to check whether
any newlines need to be added.  This way, if the original doxygen
source already includes an empty line before a block, an additional
unnecessary empty line is not added.

Updating the expected test output for doxygen_basic_translate, which
now adds the necessary empty line before the code block.  Adding
further test cases to doxygen_translate_all_tags to explicitly verify
that a newline is added in the pydoc output before both code and math
blocks that appear within a paragraph.

Additionally, empty lines previously appearing at the beginning of the
generated docstrings are now removed.  This does not alter the
behavior of the tests.

Examples/test-suite/doxygen_translate_all_tags.i

@@ -38,6 +38,10 @@
  * \cite citationword
  * \class someClass headerFile.h headerName
  * \code some test code \endcode
+ *
+ * Code immediately following text.  Pydoc translation must add an
+ * empty line before:
+ * \code more test code \endcode
  */
 void func01(int a)
 {
@@ -121,6 +125,12 @@ void func03(int a)
  *     \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
  * \f}
  *
+ * Math immediately following text.  Pydoc translation must add an
+ * empty line before:
+ * \f[
+ *     \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
+ * \f]
+ *
  * \file file.h
  *
  * \fn someFn

Examples/test-suite/java/doxygen_translate_all_tags_runme.java

@@ -40,7 +40,10 @@ public class doxygen_translate_all_tags_runme {
     		" Not everything works right now...\n" +
     		" <code>codeword</code>\n\n\n\n\n\n" +
     		" <i>citationword</i>\n" +
-                " {@code some test code }\n");
+                " {@code some test code }\n\n" +
+    		" Code immediately following text.  Pydoc translation must add an\n" +
+    		" empty line before:\n" +
+    		" {@code more test code }");
     
     wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func02(int)",
     		" Conditional comment: SOMECONDITION \n" +
@@ -63,8 +66,11 @@ public class doxygen_translate_all_tags_runme {
                        " @exception SuperError \n" +
                        " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" +
                        " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" +
-                       " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" +
+                       " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n\n" +
-    		" This will only appear in hmtl \n");
+                       "Math immediately following text.  Pydoc translation must add an\n" +
+                       "empty line before:\n\n" +
+                       " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\n" +
+                       " This will only appear in hmtl \n");
     
     wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func05(int)",
                        " If: ANOTHERCONDITION {\n" +

Examples/test-suite/python/doxygen_basic_translate_runme.py

@@ -46,6 +46,7 @@ Title: Minuses:
 * it\'s null
 
 Warning: This may not work as expected
+
 .. code-block:: c++
 
     int main() { while(true); }

Examples/test-suite/python/doxygen_basic_translate_style2_runme.py

@@ -44,6 +44,7 @@ Title: Minuses:
 * it\'s null
 
 Warning: This may not work as expected
+
 .. code-block:: c++
 
     int main() { while(true); }

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

@@ -36,7 +36,14 @@ Not everything works right now...
 
 .. code-block:: c++
 
-    some test code""")
+    some test code
+
+Code immediately following text.  Pydoc translation must add an
+empty line before:
+
+.. code-block:: c++
+
+    more test code""")
 
 comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func02),
 r"""Conditional comment: SOMECONDITION
@@ -97,6 +104,13 @@ r""":raises: SuperError
 
     \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
 
+Math immediately following text.  Pydoc translation must add an
+empty line before:
+
+.. math::
+
+    \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
+
 
 
 

Source/Doxygen/pydoc.cxx

@@ -140,16 +140,50 @@ static void trimWhitespace(string &s) {
 
 // Erase the first character in the string if it is a newline
 static void eraseLeadingNewLine(string &s) {
-  if ((! s.empty()) && s[0] == '\n')
+  if (!s.empty() && s[0] == '\n')
     s.erase(s.begin());
 }
 
 // Erase the last character in the string if it is a newline
 static void eraseTrailingNewLine(string &s) {
-  if ((! s.empty()) && s[s.size() - 1] == '\n')
+  if (!s.empty() && s[s.size() - 1] == '\n')
     s.erase(s.size() - 1);
 }
 
+// Check the generated docstring line by line and make sure that any
+// code and verbatim blocks have an empty line preceding them, which
+// is necessary for Sphinx.  Additionally, this strips any empty lines
+// appearing at the beginning of the docstring.
+static string padCodeAndVerbatimBlocks(const string &docString) {
+  std::string result;
+
+  std::istringstream iss(docString);
+
+  // Initialize to false because there is no previous line yet
+  bool lastLineWasNonBlank = false;
+  
+  for (string line; std::getline(iss, line); result += line) {
+    if (!result.empty()) {
+      // Terminate the previous line
+      result += '\n';
+    }
+
+    const size_t pos = line.find_first_not_of(" \t");
+    if (pos == string::npos) {
+      lastLineWasNonBlank = false;
+    } else {
+      if (lastLineWasNonBlank &&
+	  (line.compare(pos, 13, ".. code-block") == 0 ||
+	  line.compare(pos, 7, ".. math") == 0)) {
+	// Must separate code or math blocks from the previous line
+	result += '\n';
+      }
+      lastLineWasNonBlank = true;
+    }
+  }
+  return result;
+}
+
 /* static */
 PyDocConverter::TagHandlersMap::mapped_type PyDocConverter::make_handler(tagHandler handler) {
   return make_pair(handler, std::string());
@@ -863,6 +897,9 @@ String *PyDocConverter::makeDocumentation(Node *n) {
     // remove the last '\n' since additional one is added during writing to file
     eraseTrailingNewLine(pyDocString);
 
+    // ensure that a blank line occurs before code or math blocks
+    pyDocString = padCodeAndVerbatimBlocks(pyDocString);
+
     if (m_flags & debug_translator) {
       std::cout << "\n---RESULT IN PYDOC---" << std::endl;
       std::cout << pyDocString;