Implement translation of Doxygen formulae to Sphinx notation.

This allows to automatically have nicely looking formulae in HTML output when
using Sphinx with e.g. sphinx.ext.mathjax extension.

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

@@ -93,13 +93,16 @@ r"""
 
 
 
-      \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}
 
 
-     
+
+    .. math::
+
         \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
 
 
@@ -113,6 +116,7 @@ r"""
 
 
 
+
     This will only appear in hmtl
 
     """)

Source/DoxygenTranslator/src/PyDocConverter.cpp

@@ -147,9 +147,9 @@ void PyDocConverter::fillStaticTables()
   tagHandlers["n"] = make_handler(&PyDocConverter::handleNewLine);
 
   // \f commands output literal Latex formula, which is still better than nothing.
-  tagHandlers["f$"] = make_handler(&PyDocConverter::handleTagVerbatim);
-  tagHandlers["f["] = make_handler(&PyDocConverter::handleTagVerbatim);
-  tagHandlers["f{"] = make_handler(&PyDocConverter::handleTagVerbatim);
+  tagHandlers["f$"] =
+  tagHandlers["f["] =
+  tagHandlers["f{"] = make_handler(&PyDocConverter::handleMath);
 
   // HTML tags
   tagHandlers["<a"] = make_handler(&PyDocConverter::handleDoxyHtmlTag_A);
@@ -328,6 +328,47 @@ void PyDocConverter::handleParagraph(DoxygenEntity& tag,
   translatedComment += translateSubtree(tag);
 }
 
+void PyDocConverter::handleMath(DoxygenEntity &tag,
+                                std::string &translatedComment,
+                                const std::string& arg)
+{
+  // Only \f$ is translated to inline formulae, \f[ and \f{ are for the block ones.
+  const bool inlineFormula = tag.typeOfEntity == "f$";
+
+  if (inlineFormula) {
+    translatedComment += ":math:`";
+  } else {
+    translatedComment += ".. math::\n\n    ";
+  }
+
+  std::string formula;
+  handleTagVerbatim(tag, formula, arg);
+
+  // It is important to ensure that we have no spaces around the inline math
+  // contents, so strip them.
+  const size_t start = formula.find_first_not_of(" \t\n");
+  const size_t end = formula.find_last_not_of(" \t\n");
+  if (start != std::string::npos) {
+    for (size_t n = start; n <= end; n++) {
+      if (formula[n] == '\n') {
+        // New lines must be suppressed in inline maths and indented in the
+        // block ones.
+        if (!inlineFormula)
+          translatedComment += "\n    ";
+      } else {
+        // Just copy everything else.
+        translatedComment += formula[n];
+      }
+    }
+  }
+
+  if (inlineFormula) {
+    translatedComment += "`";
+  } else {
+    translatedComment += "\n\n";
+  }
+}
+
 void PyDocConverter::handlePlainString(DoxygenEntity& tag,
                                        std::string& translatedComment,
                                        const std::string&)

Source/DoxygenTranslator/src/PyDocConverter.h

@@ -80,6 +80,12 @@ protected:
    */
   void handleParagraph(DoxygenEntity &tag, std::string &translatedComment,
                        const std::string &arg = std::string());
+
+  /*
+   * Handle one of the Doxygen formula-related tags.
+   */
+  void handleMath(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
+
   /*
    * Print only data part of code
    */