Translate Doxygen code blocks to Sphinx code blocks.

This ensures they are formatted correctly and syntax highlighted (currently
always as C++ code).

Examples/test-suite/python/doxygen_basic_translate_runme.py

@@ -50,7 +50,10 @@ commentVerifier.check(doxygen_basic_translate.function4.__doc__,
 
     Warning: This may not work as expected
 
-    int main() { while(true); }
+    .. code-block:: c++
+
+
+        int main() { while(true); }
 
     }
     """

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

@@ -36,7 +36,11 @@ r"""
 
     'citationword'
 
-    some test code
+
+    .. code-block:: c++
+
+         some test code
+
     """)
 
 commentVerifier.check(doxygen_translate_all_tags.func02.__doc__,

Examples/test-suite/python/doxygen_translate_runme.py

@@ -22,7 +22,11 @@ r"""
 
     'citationword'
 
-    some test code
+
+    .. code-block:: c++
+
+         some test code
+
 
     Conditional comment: SOMECONDITION
     Some conditional comment

Source/DoxygenTranslator/src/PyDocConverter.cpp

@@ -153,7 +153,7 @@ void PyDocConverter::fillStaticTables()
   tagHandlers["authors"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["brief"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["bug"] = make_handler(&PyDocConverter::handleParagraph);
-  tagHandlers["code"] = make_handler(&PyDocConverter::handleParagraph);
+  tagHandlers["code"] = make_handler(&PyDocConverter::handleCode);
   tagHandlers["copyright"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["date"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["deprecated"] = make_handler(&PyDocConverter::handleParagraph);
@@ -441,6 +441,51 @@ void PyDocConverter::handleMath(DoxygenEntity &tag,
   }
 }
 
+void PyDocConverter::handleCode(DoxygenEntity &tag,
+                                std::string &translatedComment,
+                                const std::string &arg)
+{
+  IndentGuard indent(translatedComment, m_indent);
+
+  trimWhitespace(translatedComment);
+  translatedComment += '\n';
+
+  // Use the current indent for the code-block line itself.
+  string codeIndent = indent.getFirstLineIndent();
+  translatedComment += codeIndent;
+
+  // 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;
+
+  std::string code;
+  handleTagVerbatim(tag, code, arg);
+
+  translatedComment += codeIndent;
+  for (size_t n = 0; n < code.length(); n++) {
+    if (code[n] == '\n') {
+      // Don't leave trailing white space, this results in PEP8 validation
+      // errors in Python code (which are performed by our own unit tests).
+      trimWhitespace(translatedComment);
+      translatedComment += '\n';
+
+      // Ensure that we indent all the lines by the code indent.
+      translatedComment += codeIndent;
+    } else {
+      // Just copy everything else.
+      translatedComment += code[n];
+    }
+  }
+
+  trimWhitespace(translatedComment);
+  if (*translatedComment.rbegin() != '\n')
+    translatedComment += '\n';
+}
+
 void PyDocConverter::handlePlainString(DoxygenEntity& tag,
                                        std::string& translatedComment,
                                        const std::string&)

Source/DoxygenTranslator/src/PyDocConverter.h

@@ -81,6 +81,11 @@ protected:
    */
   void handleMath(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
 
+  /*
+   * Handle a code snippet.
+   */
+  void handleCode(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
+
   /*
    * Print only data part of code
    */