From e62c88883fbc9f8c5b53bc98a9d8bb0d9def5ac4 Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Thu, 23 May 2019 20:01:09 -0500
Subject: [PATCH 01/13] Fix python doxygen indentation for inline \code command

If \code was used inline, it produced an extra indent versus block
usage.  This extra indent was also stored in the test output.  This
update resolves this by simply removing a space that was being added
unnecessarily in handleTagVerbatim.  Updating test case output
accordingly.
---
 Examples/test-suite/python/doxygen_translate_all_tags_runme.py | 2 +-
 Examples/test-suite/python/doxygen_translate_runme.py          | 2 +-
 Source/Doxygen/pydoc.cxx                                       | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
index 53d087e69..e269b8c18 100644
--- a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
+++ b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
@@ -37,7 +37,7 @@ Not everything works right now...
 
 .. code-block:: c++
 
-     some test code""")
+    some test code""")
 
 comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func02),
 r"""Conditional comment: SOMECONDITION
diff --git a/Examples/test-suite/python/doxygen_translate_runme.py b/Examples/test-suite/python/doxygen_translate_runme.py
index 2d0840a1f..50292e30c 100644
--- a/Examples/test-suite/python/doxygen_translate_runme.py
+++ b/Examples/test-suite/python/doxygen_translate_runme.py
@@ -23,7 +23,7 @@ Author: Zubr
 
 .. code-block:: c++
 
-     some test code
+    some test code
 
 
 Conditional comment: SOMECONDITION
diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index fc3b0ea09..5dff07df2 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/Source/Doxygen/pydoc.cxx
@@ -519,7 +519,7 @@ void PyDocConverter::handlePlainString(DoxygenEntity &tag, std::string &translat
 }
 
 void PyDocConverter::handleTagVerbatim(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) {
-  translatedComment += arg + " ";
+  translatedComment += arg;
   for (DoxygenEntityListCIt it = tag.entityList.begin(); it != tag.entityList.end(); it++) {
     translatedComment += it->data;
   }

From 3d64a2c03760b0c955cfb6d4b3c17444bfd4c83a Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sat, 25 May 2019 13:14:14 -0500
Subject: [PATCH 02/13] Remove extra newline in beginning of doxygen python
 \code command

If \code is used as a block command (probably the main use case), an
extra newline was included in the translated Python comments.  This is
now removed and doxygen python test case output updated.
---
 Examples/test-suite/python/doxygen_basic_translate_runme.py | 1 -
 Source/Doxygen/pydoc.cxx                                    | 5 +++++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/Examples/test-suite/python/doxygen_basic_translate_runme.py b/Examples/test-suite/python/doxygen_basic_translate_runme.py
index e664e06f6..585783d16 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_runme.py
+++ b/Examples/test-suite/python/doxygen_basic_translate_runme.py
@@ -49,7 +49,6 @@ Warning: This may not work as expected
 
 .. code-block:: c++
 
-
     int main() { while(true); }
 
 }"""
diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index 5dff07df2..fe918b0ab 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/Source/Doxygen/pydoc.cxx
@@ -493,6 +493,11 @@ void PyDocConverter::handleCode(DoxygenEntity &tag, std::string &translatedComme
   std::string code;
   handleTagVerbatim(tag, code, arg);
 
+  // Try and remove leading newline, which is present for block \code
+  // command:
+  if (code[0] == '\n')
+    code.erase(code.begin());
+
   translatedComment += codeIndent;
   for (size_t n = 0; n < code.length(); n++) {
     if (code[n] == '\n') {

From 321cb096a88d6cbb9a6709d7304b0134624d3181 Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sat, 25 May 2019 13:40:59 -0500
Subject: [PATCH 03/13] Remove extra newline from end of doxygen python \code
 command

Remove the extra newline at the end of translation of doxygen \code
\endcode command for Python.  Update test output accordingly.
---
 .../test-suite/python/doxygen_basic_translate_runme.py |  1 -
 Examples/test-suite/python/doxygen_translate_runme.py  |  1 -
 Source/Doxygen/pydoc.cxx                               | 10 +++++++---
 3 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/Examples/test-suite/python/doxygen_basic_translate_runme.py b/Examples/test-suite/python/doxygen_basic_translate_runme.py
index 585783d16..b6023224d 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_runme.py
+++ b/Examples/test-suite/python/doxygen_basic_translate_runme.py
@@ -50,7 +50,6 @@ Warning: This may not work as expected
 .. code-block:: c++
 
     int main() { while(true); }
-
 }"""
 )
 comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function5),
diff --git a/Examples/test-suite/python/doxygen_translate_runme.py b/Examples/test-suite/python/doxygen_translate_runme.py
index 50292e30c..8af5953d1 100644
--- a/Examples/test-suite/python/doxygen_translate_runme.py
+++ b/Examples/test-suite/python/doxygen_translate_runme.py
@@ -25,7 +25,6 @@ Author: Zubr
 
     some test code
 
-
 Conditional comment: SOMECONDITION
 Some conditional comment
 End of conditional comment.
diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index fe918b0ab..736e09458 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/Source/Doxygen/pydoc.cxx
@@ -495,7 +495,7 @@ void PyDocConverter::handleCode(DoxygenEntity &tag, std::string &translatedComme
 
   // Try and remove leading newline, which is present for block \code
   // command:
-  if (code[0] == '\n')
+  if ((! code.empty()) && code[0] == '\n')
     code.erase(code.begin());
 
   translatedComment += codeIndent;
@@ -515,8 +515,12 @@ void PyDocConverter::handleCode(DoxygenEntity &tag, std::string &translatedComme
   }
 
   trimWhitespace(translatedComment);
-  if (*translatedComment.rbegin() != '\n')
-    translatedComment += '\n';
+
+  // For block commands, the translator adds the newline after
+  // \endcode, so try and compensate by removing the last newline from
+  // the code text:
+  if ((! translatedComment.empty()) && translatedComment[translatedComment.size()-1] == '\n')
+    translatedComment = translatedComment.substr(0, translatedComment.size()-1); // use translatedComment.pop_back() in C++ 11
 }
 
 void PyDocConverter::handlePlainString(DoxygenEntity &tag, std::string &translatedComment, const std::string &) {

From c52bed2e668166ab661de20e2147e56d24ca3d2b Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sat, 25 May 2019 14:15:44 -0500
Subject: [PATCH 04/13] Eliminate extra newlines in doxygen python \verbatim
 blocks

Eliminate extra leading and trailing newlines present in translated
doxygen \verbatim comments for python.  Updating doxygen python tests
accordingly.
---
 .../python/doxygen_translate_all_tags_runme.py    |  2 --
 .../test-suite/python/doxygen_translate_runme.py  |  2 --
 Source/Doxygen/pydoc.cxx                          | 15 ++++++++++++++-
 Source/Doxygen/pydoc.h                            |  5 +++++
 4 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
index e269b8c18..7cf09fb56 100644
--- a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
+++ b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
@@ -283,13 +283,11 @@ r"""TODO: Some very important task
 
 
 
-
 very long
 text with tags <sometag>
 
 
 
-
 Version: 0.0.0.2
 
 Warning: This is senseless!
diff --git a/Examples/test-suite/python/doxygen_translate_runme.py b/Examples/test-suite/python/doxygen_translate_runme.py
index 8af5953d1..7d127454b 100644
--- a/Examples/test-suite/python/doxygen_translate_runme.py
+++ b/Examples/test-suite/python/doxygen_translate_runme.py
@@ -120,11 +120,9 @@ TODO: Some very important task
 :type b: float
 :param b: B is mentioned again...
 
-
 very long
 text with tags <sometag>
 
-
 Version: 0.0.0.2
 
 Warning: This is senseless!
diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index 736e09458..31ec972d6 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/Source/Doxygen/pydoc.cxx
@@ -219,7 +219,7 @@ void PyDocConverter::fillStaticTables() {
   tagHandlers["short"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["todo"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["version"] = make_handler(&PyDocConverter::handleParagraph);
-  tagHandlers["verbatim"] = make_handler(&PyDocConverter::handleParagraph);
+  tagHandlers["verbatim"] = make_handler(&PyDocConverter::handleVerbatimBlock);
   tagHandlers["warning"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["xmlonly"] = make_handler(&PyDocConverter::handleParagraph);
   // these commands have special handlers
@@ -419,6 +419,19 @@ void PyDocConverter::handleParagraph(DoxygenEntity &tag, std::string &translated
   translatedComment += translateSubtree(tag);
 }
 
+void PyDocConverter::handleVerbatimBlock(DoxygenEntity &tag, std::string &translatedComment, const std::string &) {
+  string verb = translateSubtree(tag);
+
+  if ((! verb.empty()) && verb[0] == '\n')
+    verb.erase(verb.begin());
+  
+  // Remove the last newline to prevent doubling the newline already present after \endverbatim
+  trimWhitespace(verb); // Needed to catch trailing newline below
+  if ((! verb.empty()) && verb[verb.size()-1] == '\n')
+    verb = verb.substr(0, verb.size()-1);
+  translatedComment += verb;
+}
+
 void PyDocConverter::handleMath(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) {
   IndentGuard indent;
 
diff --git a/Source/Doxygen/pydoc.h b/Source/Doxygen/pydoc.h
index 8f432fd18..df8997d76 100644
--- a/Source/Doxygen/pydoc.h
+++ b/Source/Doxygen/pydoc.h
@@ -79,6 +79,11 @@ protected:
    */
   void handleParagraph(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg = std::string());
 
+  /*
+   * Handle Doxygen verbatim tag
+   */
+  void handleVerbatimBlock(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg = std::string());
+
   /*
    * Handle one of the Doxygen formula-related tags.
    */

From 08fc4a02b4df7f4a53b375e37820c88b375fe9a8 Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sat, 25 May 2019 14:33:41 -0500
Subject: [PATCH 05/13] Eliminate extra newlines around doxygen python block
 math

Eliminate extra leading and trailing newlines around the \f[ and \f{
block math commands for doxygen comment translation for python.
Update tests accordingly.
---
 .../test-suite/python/doxygen_translate_all_tags_runme.py     | 4 ----
 Source/Doxygen/pydoc.cxx                                      | 3 ---
 2 files changed, 7 deletions(-)

diff --git a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
index 7cf09fb56..78bf73870 100644
--- a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
+++ b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
@@ -90,13 +90,10 @@ r""":raises: SuperError
 
 :math:`\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}`
 
-
 .. math::
 
     \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
 
-
-
 .. math::
 
     \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
@@ -111,7 +108,6 @@ r""":raises: SuperError
 
 
 
-
 This will only appear in hmtl""")
 
 comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func05),
diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index 31ec972d6..688318dd9 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/Source/Doxygen/pydoc.cxx
@@ -446,7 +446,6 @@ void PyDocConverter::handleMath(DoxygenEntity &tag, std::string &translatedComme
     indent.Init(translatedComment, m_indent);
 
     trimWhitespace(translatedComment);
-    translatedComment += '\n';
 
     const string formulaIndent = indent.getFirstLineIndent();
     translatedComment += formulaIndent;
@@ -480,8 +479,6 @@ void PyDocConverter::handleMath(DoxygenEntity &tag, std::string &translatedComme
 
   if (inlineFormula) {
     translatedComment += "`";
-  } else {
-    translatedComment += '\n';
   }
 }
 

From 98ae66b6fcaaee19f62141bb3c30de0ae6ff7cca Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sat, 25 May 2019 15:12:05 -0500
Subject: [PATCH 06/13] Fix bug in doxygen python code block indent

If a certain doxygen comment style was used that included an
additional space, then translated Python comment code block indent was
not correct (it included the extra space).  This doxygen comment style
was not previously represented in the test cases; a new test case will
be added in a subsequent commit.
---
 Source/Doxygen/pydoc.cxx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index 688318dd9..3eb855058 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/Source/Doxygen/pydoc.cxx
@@ -498,7 +498,7 @@ void PyDocConverter::handleCode(DoxygenEntity &tag, std::string &translatedComme
   translatedComment += ".. code-block:: c++\n\n";
 
   // For now on, use extra indent level for all the subsequent lines.
-  codeIndent += m_indent;
+  codeIndent = m_indent;
 
   std::string code;
   handleTagVerbatim(tag, code, arg);

From 91a90b8d27e759d5504bc3be72a300fe4c68b8ad Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sat, 25 May 2019 11:34:15 -0500
Subject: [PATCH 07/13] Adding test for second doxygen comment style

This style looks like:

/** Line 1
 *  Line 2
 */

This is needed to verify fixes to some of the indentation in the
translated comments.

The test is copied from doxygen_basic_translate.i.  One adjustment was
made to change the comment style on the last function that left out
the intermediate "*" characters.  This does not produce correct output
when combined with this style of starting the text on the first
comment line.

Test results are copied directly from doxygen_basic_translate.  A
minor difference in the Python results will be updated in a subsequent
commit.
---
 Examples/test-suite/common.mk                 |   1 +
 .../doxygen_basic_translate_style2.i          | 105 ++++++++++++++++++
 .../doxygen_basic_translate_style2_runme.java |  99 +++++++++++++++++
 .../doxygen_basic_translate_style2_runme.py   |  82 ++++++++++++++
 4 files changed, 287 insertions(+)
 create mode 100644 Examples/test-suite/doxygen_basic_translate_style2.i
 create mode 100644 Examples/test-suite/java/doxygen_basic_translate_style2_runme.java
 create mode 100644 Examples/test-suite/python/doxygen_basic_translate_style2_runme.py

diff --git a/Examples/test-suite/common.mk b/Examples/test-suite/common.mk
index 67a63287d..eece29b00 100644
--- a/Examples/test-suite/common.mk
+++ b/Examples/test-suite/common.mk
@@ -620,6 +620,7 @@ DOXYGEN_TEST_CASES += \
 	doxygen_alias \
 	doxygen_basic_notranslate \
 	doxygen_basic_translate \
+	doxygen_basic_translate_style2 \
 	doxygen_ignore \
 	doxygen_misc_constructs \
 	doxygen_nested_class \
diff --git a/Examples/test-suite/doxygen_basic_translate_style2.i b/Examples/test-suite/doxygen_basic_translate_style2.i
new file mode 100644
index 000000000..23e8de4f7
--- /dev/null
+++ b/Examples/test-suite/doxygen_basic_translate_style2.i
@@ -0,0 +1,105 @@
+%module doxygen_basic_translate_style2
+
+%include "doxygen_basic_translate.h"
+
+// This test demonstrates a doxygen comment style that starts on the
+// first line and so uses extra spacing in subsequent lines.
+
+%inline %{
+
+/** \brief
+ *  Brief description.
+ * 
+ *  The comment text.
+ *
+ *  \author Some author
+ *
+ *  \return Some number
+ *
+ *  \sa function2
+ */
+int function()
+{
+    return 0;
+}
+
+/** A test of a very very very very very very very very very very very very very very very very
+ *  very very very very very long comment string.
+ */
+void function2()
+{
+}
+
+/** A test for overloaded functions
+ *  This is function \b one
+ */
+void function3(int a)
+{
+}
+
+/** A test for overloaded functions
+ *  This is function \b two
+ */
+void function3(int a, int b)
+{
+}
+
+/** A test of some mixed tag usage
+ *  \if CONDITION
+ *  This \a code fragment shows us something \.
+ *  \par Minuses:
+ *  \arg it's senseless
+ *  \arg it's stupid
+ *  \arg it's null
+ *
+ *  \warning This may not work as expected
+ *  \code
+ *  int main() { while(true); }
+ *  \endcode
+ *  \endif
+ */
+void function4()
+{
+}
+
+
+void function5(int a)
+{
+}
+/**< This is a post comment. */
+
+/** Test for default args
+ *  @param a Some parameter, default is 42
+ */
+void function6(int a=42)
+{
+}
+
+class Shape
+{
+public:
+  typedef Shape* superType;
+};
+
+/** Test for a parameter with difficult type
+ *  (mostly for python)
+ *  @param a Very strange param
+ */
+void function7(Shape::superType *a[10])
+{
+}
+
+/** Multiple parameters test.
+ *
+ *  @param y Vertical coordinate.
+ *  @param x Horizontal coordinate.
+ *  @return Arc tangent of @c y/x.
+ */
+double Atan2(double y, double x)
+{
+    return 0;
+}
+
+/** Comment at the end of file should be ignored.
+ */
+%}
diff --git a/Examples/test-suite/java/doxygen_basic_translate_style2_runme.java b/Examples/test-suite/java/doxygen_basic_translate_style2_runme.java
new file mode 100644
index 000000000..aa015eeac
--- /dev/null
+++ b/Examples/test-suite/java/doxygen_basic_translate_style2_runme.java
@@ -0,0 +1,99 @@
+
+import doxygen_basic_translate_style2.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_basic_translate_style2_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_basic_translate_style2");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_basic_translate_style2 runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_basic_translate_style2"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function()",
+    		" \n" +
+    		" Brief description.\n" +
+    		" \n" +
+    		" The comment text.\n" +
+    		" @author Some author\n" +
+    		" @return Some number\n" +
+    		" @see function2\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function2()",
+    		" A test of a very very very very very very very very very very very very very very very very \n" +
+    		" very very very very very long comment string. \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function4()",
+    		" A test of some mixed tag usage \n" +
+    		" If: CONDITION {\n" +
+    		" This <i>code </i>fragment shows us something . \n" +
+    		" <p alt=\"Minuses: \">\n" +
+    		" <li>it's senseless \n" +
+    		" </li><li>it's stupid \n" +
+    		" </li><li>it's null \n" +
+    		" \n" +
+    		" </li></p>Warning: This may not work as expected \n" +
+    		" \n" +
+    		" {@code \n" +
+    		"int main() { while(true); } \n" +
+    		" }\n" +
+    		" }\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function3(int)",
+    		" A test for overloaded functions \n" +
+    		" This is function <b>one </b>\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function5(int)",
+    		" This is a post comment. \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function6(int)",
+    		" Test for default args \n" +
+    		" @param a Some parameter, default is 42" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function6()",
+    		" Test for default args \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function7(doxygen_basic_translate_style2.SWIGTYPE_p_p_p_Shape)",
+    		" Test for a parameter with difficult type \n" +
+    		" (mostly for python) \n" +
+    		" @param a Very strange param \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function3(int, int)",
+    		" A test for overloaded functions \n" +
+    		" This is function <b>two </b>\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.Atan2(double, double)",
+    		" Multiple parameters test.\n" +
+    		" \n" +
+    		" @param y Vertical coordinate.\n" +
+    		" @param x Horizontal coordinate.\n" +
+    		" @return Arc tangent of <code>y/x</code>.\n" +
+    		"");
+
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}
diff --git a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py b/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
new file mode 100644
index 000000000..c8d24ab72
--- /dev/null
+++ b/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
@@ -0,0 +1,82 @@
+import doxygen_basic_translate_spaced
+import inspect
+import string
+import sys
+import comment_verifier
+
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function),
+    """\
+Brief description.
+
+The comment text.
+
+Author: Some author
+
+:rtype: int
+:return: Some number
+
+See also: function2"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function2),
+    """\
+A test of a very very very very very very very very very very very very very very very very
+very very very very very long comment string."""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function3),
+    """*Overload 1:*
+
+A test for overloaded functions
+This is function **one**
+
+|
+
+*Overload 2:*
+
+A test for overloaded functions
+This is function **two**"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function4),
+    """\
+A test of some mixed tag usage
+If: CONDITION {
+This *code* fragment shows us something .
+Title: Minuses:
+* it\'s senseless
+* it\'s stupid
+* it\'s null
+
+Warning: This may not work as expected
+
+.. code-block:: c++
+
+    int main() { while(true); }
+}"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function5),
+    """This is a post comment."""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function6),
+    """\
+Test for default args
+:type a: int
+:param a: Some parameter, default is 42"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function7),
+    """\
+Test for a parameter with difficult type
+(mostly for python)
+:type a: :py:class:`Shape`
+:param a: Very strange param"""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.Atan2),
+    """\
+Multiple parameters test.
+
+:type y: float
+:param y: Vertical coordinate.
+:type x: float
+:param x: Horizontal coordinate.
+:rtype: float
+:return: Arc tangent of ``y/x``."""
+)

From 0395c48124a89ef69886d0ebaeb6a3c533ceb38b Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sat, 25 May 2019 11:39:36 -0500
Subject: [PATCH 08/13] Adjust expected python output for doxygen style2 test

Observed that with this second comment style, there is no line break
after the function overload headings in the translated
comments. Updating the test results accordingly.
---
 .../test-suite/python/doxygen_basic_translate_style2_runme.py   | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py b/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
index c8d24ab72..5d36d216d 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
+++ b/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
@@ -24,14 +24,12 @@ very very very very very long comment string."""
 )
 comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function3),
     """*Overload 1:*
-
 A test for overloaded functions
 This is function **one**
 
 |
 
 *Overload 2:*
-
 A test for overloaded functions
 This is function **two**"""
 )

From 64b2113e66b88e9ac605e0691e062fd2d46fe2fe Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sun, 26 May 2019 07:50:06 -0500
Subject: [PATCH 09/13] Correction to recently added doxygen python test case

The _runme.py code for the recently added test case was using
references to an old module name for the test case, which was later
changed but not updated in the runme file.
---
 .../doxygen_basic_translate_style2_runme.py    | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py b/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
index 5d36d216d..2d62eecbd 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
+++ b/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
@@ -1,10 +1,10 @@
-import doxygen_basic_translate_spaced
+import doxygen_basic_translate_style2
 import inspect
 import string
 import sys
 import comment_verifier
 
-comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function),
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function),
     """\
 Brief description.
 
@@ -17,12 +17,12 @@ Author: Some author
 
 See also: function2"""
 )
-comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function2),
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function2),
     """\
 A test of a very very very very very very very very very very very very very very very very
 very very very very very long comment string."""
 )
-comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function3),
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function3),
     """*Overload 1:*
 A test for overloaded functions
 This is function **one**
@@ -33,7 +33,7 @@ This is function **one**
 A test for overloaded functions
 This is function **two**"""
 )
-comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function4),
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function4),
     """\
 A test of some mixed tag usage
 If: CONDITION {
@@ -50,16 +50,16 @@ Warning: This may not work as expected
     int main() { while(true); }
 }"""
 )
-comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function5),
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function5),
     """This is a post comment."""
 )
-comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function6),
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function6),
     """\
 Test for default args
 :type a: int
 :param a: Some parameter, default is 42"""
 )
-comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function7),
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function7),
     """\
 Test for a parameter with difficult type
 (mostly for python)
@@ -67,7 +67,7 @@ Test for a parameter with difficult type
 :param a: Very strange param"""
 )
 
-comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.Atan2),
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.Atan2),
     """\
 Multiple parameters test.
 

From 0c6930d96672775326ad658773ff80f66dc2abad Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sun, 26 May 2019 07:40:19 -0500
Subject: [PATCH 10/13] Cleanup of pydoc translator newline trimming

Simplify python doxygen translation code by using functions to erase
leading and trailing newlines.  No change to logic.
---
 Source/Doxygen/pydoc.cxx | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index 3eb855058..ad304e28e 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/Source/Doxygen/pydoc.cxx
@@ -138,6 +138,18 @@ static void trimWhitespace(string &s) {
     s.erase(lastNonSpace + 1);
 }
 
+// Erase the first character in the string if it is a newline
+static void eraseLeadingNewLine(string &s) {
+  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')
+    s.erase(s.size() - 1);
+}
+
 /* static */
 PyDocConverter::TagHandlersMap::mapped_type PyDocConverter::make_handler(tagHandler handler) {
   return make_pair(handler, std::string());
@@ -422,13 +434,11 @@ void PyDocConverter::handleParagraph(DoxygenEntity &tag, std::string &translated
 void PyDocConverter::handleVerbatimBlock(DoxygenEntity &tag, std::string &translatedComment, const std::string &) {
   string verb = translateSubtree(tag);
 
-  if ((! verb.empty()) && verb[0] == '\n')
-    verb.erase(verb.begin());
-  
+  eraseLeadingNewLine(verb);
+
   // Remove the last newline to prevent doubling the newline already present after \endverbatim
   trimWhitespace(verb); // Needed to catch trailing newline below
-  if ((! verb.empty()) && verb[verb.size()-1] == '\n')
-    verb = verb.substr(0, verb.size()-1);
+  eraseTrailingNewLine(verb);
   translatedComment += verb;
 }
 
@@ -505,8 +515,7 @@ void PyDocConverter::handleCode(DoxygenEntity &tag, std::string &translatedComme
 
   // Try and remove leading newline, which is present for block \code
   // command:
-  if ((! code.empty()) && code[0] == '\n')
-    code.erase(code.begin());
+  eraseLeadingNewLine(code);
 
   translatedComment += codeIndent;
   for (size_t n = 0; n < code.length(); n++) {
@@ -529,8 +538,7 @@ void PyDocConverter::handleCode(DoxygenEntity &tag, std::string &translatedComme
   // For block commands, the translator adds the newline after
   // \endcode, so try and compensate by removing the last newline from
   // the code text:
-  if ((! translatedComment.empty()) && translatedComment[translatedComment.size()-1] == '\n')
-    translatedComment = translatedComment.substr(0, translatedComment.size()-1); // use translatedComment.pop_back() in C++ 11
+  eraseTrailingNewLine(translatedComment);
 }
 
 void PyDocConverter::handlePlainString(DoxygenEntity &tag, std::string &translatedComment, const std::string &) {
@@ -852,9 +860,7 @@ String *PyDocConverter::makeDocumentation(Node *n) {
   if (!pyDocString.empty()) {
 
     // remove the last '\n' since additional one is added during writing to file
-    if (pyDocString[pyDocString.size() - 1] == '\n') {
-      pyDocString.erase(pyDocString.size() - 1);
-    }
+    eraseTrailingNewLine(pyDocString);
 
     if (m_flags & debug_translator) {
       std::cout << "\n---RESULT IN PYDOC---" << std::endl;

From 08ac56b7f26b21b33426ca482c017f3a6f654855 Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sun, 26 May 2019 08:19:07 -0500
Subject: [PATCH 11/13] Clarify python doxygen code block indentation handling

Clarify usage and comments for the codeIndent string, the intent of
which was not clear after recent updates.
---
 Source/Doxygen/pydoc.cxx | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index ad304e28e..fc210f106 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/Source/Doxygen/pydoc.cxx
@@ -499,16 +499,18 @@ void PyDocConverter::handleCode(DoxygenEntity &tag, std::string &translatedComme
   translatedComment += '\n';
 
   // Use the current indent for the code-block line itself.
-  string codeIndent = indent.getFirstLineIndent();
-  translatedComment += codeIndent;
+  translatedComment += indent.getFirstLineIndent();
 
   // Go out on a limb and assume that examples in the C or C++ sources use C++.
   // In the worst case, we'll highlight C code using C++ syntax which is not a
   // big deal (TODO: handle Doxygen code command language argument).
   translatedComment += ".. code-block:: c++\n\n";
 
-  // For now on, use extra indent level for all the subsequent lines.
-  codeIndent = m_indent;
+  // Specify the level of extra indentation that will be used for
+  // subsequent lines within the code block.  Note that the correct
+  // "starting indentation" is already present in the input, so we
+  // only need to add the desired code block indentation.
+  string codeIndent = m_indent;
 
   std::string code;
   handleTagVerbatim(tag, code, arg);

From 347656566510344f4eb8a772d83afd17699d5f60 Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Mon, 27 May 2019 13:04:15 -0500
Subject: [PATCH 12/13] Remove extra newline before code block in doxygen
 python output

Remove a newline character that was added to the translated comments
prior to the code block.  This way the structure of the pydoc output
more closely resembles that of the original doxygen comments.
Updating tests accordingly.
---
 Examples/test-suite/python/doxygen_basic_translate_runme.py      | 1 -
 .../test-suite/python/doxygen_basic_translate_style2_runme.py    | 1 -
 Examples/test-suite/python/doxygen_translate_all_tags_runme.py   | 1 -
 Examples/test-suite/python/doxygen_translate_runme.py            | 1 -
 Source/Doxygen/pydoc.cxx                                         | 1 -
 5 files changed, 5 deletions(-)

diff --git a/Examples/test-suite/python/doxygen_basic_translate_runme.py b/Examples/test-suite/python/doxygen_basic_translate_runme.py
index b6023224d..0690aa464 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_runme.py
+++ b/Examples/test-suite/python/doxygen_basic_translate_runme.py
@@ -46,7 +46,6 @@ Title: Minuses:
 * it\'s null
 
 Warning: This may not work as expected
-
 .. code-block:: c++
 
     int main() { while(true); }
diff --git a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py b/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
index 2d62eecbd..f7d68f410 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
+++ b/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
@@ -44,7 +44,6 @@ Title: Minuses:
 * it\'s null
 
 Warning: This may not work as expected
-
 .. code-block:: c++
 
     int main() { while(true); }
diff --git a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
index 78bf73870..22aec872d 100644
--- a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
+++ b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
@@ -34,7 +34,6 @@ Not everything works right now...
 
 'citationword'
 
-
 .. code-block:: c++
 
     some test code""")
diff --git a/Examples/test-suite/python/doxygen_translate_runme.py b/Examples/test-suite/python/doxygen_translate_runme.py
index 7d127454b..d698ba873 100644
--- a/Examples/test-suite/python/doxygen_translate_runme.py
+++ b/Examples/test-suite/python/doxygen_translate_runme.py
@@ -20,7 +20,6 @@ Author: Zubr
 
 'citationword'
 
-
 .. code-block:: c++
 
     some test code
diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index fc210f106..f40541b00 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/Source/Doxygen/pydoc.cxx
@@ -496,7 +496,6 @@ void PyDocConverter::handleCode(DoxygenEntity &tag, std::string &translatedComme
   IndentGuard indent(translatedComment, m_indent);
 
   trimWhitespace(translatedComment);
-  translatedComment += '\n';
 
   // Use the current indent for the code-block line itself.
   translatedComment += indent.getFirstLineIndent();

From daad5d664d745c15657de19e6509f1e189e01109 Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Tue, 4 Jun 2019 16:55:54 -0500
Subject: [PATCH 13/13] 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.
---
 .../test-suite/doxygen_translate_all_tags.i   | 10 +++++
 .../doxygen_translate_all_tags_runme.java     | 12 ++++--
 .../python/doxygen_basic_translate_runme.py   |  1 +
 .../doxygen_basic_translate_style2_runme.py   |  1 +
 .../doxygen_translate_all_tags_runme.py       | 16 +++++++-
 Source/Doxygen/pydoc.cxx                      | 41 ++++++++++++++++++-
 6 files changed, 75 insertions(+), 6 deletions(-)

diff --git a/Examples/test-suite/doxygen_translate_all_tags.i b/Examples/test-suite/doxygen_translate_all_tags.i
index 6e96a57c5..8da683d52 100644
--- a/Examples/test-suite/doxygen_translate_all_tags.i
+++ b/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
diff --git a/Examples/test-suite/java/doxygen_translate_all_tags_runme.java b/Examples/test-suite/java/doxygen_translate_all_tags_runme.java
index 8bd65224f..d5c533f4e 100644
--- a/Examples/test-suite/java/doxygen_translate_all_tags_runme.java
+++ b/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" +
-    		" This will only appear in hmtl \n");
+                       " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n\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" +
diff --git a/Examples/test-suite/python/doxygen_basic_translate_runme.py b/Examples/test-suite/python/doxygen_basic_translate_runme.py
index 0690aa464..b6023224d 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_runme.py
+++ b/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); }
diff --git a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py b/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
index f7d68f410..2d62eecbd 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
+++ b/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); }
diff --git a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
index 22aec872d..df1c0eba5 100644
--- a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
+++ b/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}
+
 
 
 
diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index f40541b00..eb489932a 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/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;