From: Vladimír Vondruš <mosra@centrum.cz>
Date: Sun, 15 Sep 2024 20:02:57 +0000 (+0200)
Subject: documentation/doxygen: support the M_MATH_RENDER_AS_CODE option.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=7baa5a32a9d3ef8ddc9671b387ac83bce8271c62;p=blog.git

documentation/doxygen: support the M_MATH_RENDER_AS_CODE option.
---

diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst
index b21068fa..4c14d5c3 100644
--- a/doc/documentation/doxygen.rst
+++ b/doc/documentation/doxygen.rst
@@ -455,6 +455,10 @@ Variable                            Description
                                     output directory is used. Equivalent to an
                                     option of the same name in the
                                     `m.math plugin <{filename}/plugins/math-and-code.rst#math>`.
+:py:`M_MATH_RENDER_AS_CODE`         Don't invoke LaTex and render math as
+                                    inline code and code blocks. Equivalent to
+                                    an option of the same name in the
+                                    `m.math plugin <{filename}/plugins/math-and-code.rst#math>`.
 :py:`M_CODE_FILTERS_PRE: Dict`      Filters to apply before a code snippet is
                                     rendered. Equivalent to an option of the
                                     same name in the `m.code plugin <{filename}/plugins/math-and-code.rst#filters>`.
diff --git a/doc/plugins/math-and-code.rst b/doc/plugins/math-and-code.rst
index cc634ac9..9839c638 100644
--- a/doc/plugins/math-and-code.rst
+++ b/doc/plugins/math-and-code.rst
@@ -81,9 +81,8 @@ for block-level math or the ``@f$`` command for inline math. It's possible to
 add extra CSS classes by placing ``@m_class`` in a paragraph before the actual
 math block (or right before inline math), see the
 `Doxygen theme-specific commands <http://localhost:8000/documentation/doxygen/#theme-specific-commands>`_
-for more information. The :ini:`M_MATH_CACHE_FILE` option is supported as well;
-there's no equivalent to the :ini:`M_MATH_RENDER_AS_CODE` option implemented at
-this point.
+for more information. The :ini:`M_MATH_CACHE_FILE` and
+:ini:`M_MATH_RENDER_AS_CODE` options are supported as well.
 
 In addition you need some LaTeX distribution installed. Use your distribution
 package manager, for example on Ubuntu:
diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 8eddba96..d06561cf 100755
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -133,6 +133,7 @@ default_config = {
     'CLASS_INDEX_EXPAND_INNER': False,
 
     'M_MATH_CACHE_FILE': 'm.math.cache',
+    'M_MATH_RENDER_AS_CODE': False,
     'M_CODE_FILTERS_PRE': {},
     'M_CODE_FILTERS_POST': {},
 
@@ -1394,23 +1395,34 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
 
             logging.debug("{}: rendering math: {}".format(state.current, i.text))
 
-            # Assume that Doxygen wrapped the formula properly to distinguish
-            # between inline, block or special environment
-            depth, svg = latex2svgextra.fetch_cached_or_render('{}'.format(i.text))
-
             # We should have decided about block/inline above
             assert formula_block is not None
-            if formula_block:
-                has_block_elements = True
-                out.parsed += '<div class="m-math{}">{}</div>'.format(
-                    ' ' + add_css_class if add_css_class else '',
-                    latex2svgextra.patch(i.text, svg, None, ''))
+
+            # Fallback rendering as code requested
+            if state.config['M_MATH_RENDER_AS_CODE']:
+                out.parsed += '<{0} class="m-code{1}{2}">{3}</{0}>'.format(
+                    'pre' if formula_block else 'code',
+                    ' ' + add_css_class if formula_block and add_css_class else '',
+                    # TODO try w/ this removed
+                    ' ' + add_inline_css_class if not formula_block and add_inline_css_class else '',
+                    i.text)
             else:
-                # CSS classes and styling for proper vertical alignment. Depth is relative
-                # to font size, describes how below the line the text is. Scaling it back
-                # to 12pt font, scaled by 125% as set above in the config.
-                attribs = ' class="m-math{}"'.format(' ' + add_inline_css_class if add_inline_css_class else '')
-                out.parsed += latex2svgextra.patch(i.text, svg, depth, attribs)
+                # Assume that Doxygen wrapped the formula properly to
+                # distinguish between inline, block or special environment
+                depth, svg = latex2svgextra.fetch_cached_or_render('{}'.format(i.text))
+
+                if formula_block:
+                    has_block_elements = True
+                    out.parsed += '<div class="m-math{}">{}</div>'.format(
+                        ' ' + add_css_class if add_css_class else '',
+                        latex2svgextra.patch(i.text, svg, None, ''))
+                else:
+                    # CSS classes and styling for proper vertical alignment.
+                    # Depth is relative to font size, describes how below the
+                    # line the text is. Scaling it back to 12pt font, scaled by
+                    # 125% as set above in the config.
+                    attribs = ' class="m-math{}"'.format(' ' + add_inline_css_class if add_inline_css_class else '')
+                    out.parsed += latex2svgextra.patch(i.text, svg, depth, attribs)
 
         # Inline elements
         elif i.tag == 'linebreak':
@@ -3912,6 +3924,7 @@ def parse_doxyfile(state: State, doxyfile, values = None):
         ('M_VERSION_LABELS', 'VERSION_LABELS', bool),
 
         ('M_MATH_CACHE_FILE', 'M_MATH_CACHE_FILE', str),
+        ('M_MATH_RENDER_AS_CODE', 'M_MATH_RENDER_AS_CODE', bool),
     ]:
         if key not in values: continue
 
diff --git a/documentation/test_doxygen/contents_math_code_fallback/Doxyfile b/documentation/test_doxygen/contents_math_code_fallback/Doxyfile
new file mode 100644
index 00000000..fa824055
--- /dev/null
+++ b/documentation/test_doxygen/contents_math_code_fallback/Doxyfile
@@ -0,0 +1,19 @@
+INPUT                   = input.dox
+QUIET                   = YES
+GENERATE_HTML           = NO
+GENERATE_LATEX          = NO
+GENERATE_XML            = YES
+XML_PROGRAMLISTING      = NO
+CASE_SENSE_NAMES        = YES
+
+##! M_PAGE_FINE_PRINT   =
+##! M_THEME_COLOR       =
+##! M_FAVICON           =
+##! M_LINKS_NAVBAR1     =
+##! M_LINKS_NAVBAR2     =
+##! M_SEARCH_DISABLED   = YES
+##! M_MATH_CACHE_FILE   =
+##! M_MATH_RENDER_AS_CODE = YES
+
+ALIASES = \
+    "m_class{1}=@xmlonly<mcss:class xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\" />@endxmlonly"
diff --git a/documentation/test_doxygen/contents_math_code_fallback/index-191.html b/documentation/test_doxygen/contents_math_code_fallback/index-191.html
new file mode 100644
index 00000000..d8118914
--- /dev/null
+++ b/documentation/test_doxygen/contents_math_code_fallback/index-191.html
@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          My Project
+        </h1>
+<p>Here&#x27;s a block formula:</p><pre class="m-code">\[ \hat q = [\boldsymbol 0, 1] + \epsilon [\frac{\boldsymbol v}{2}, 0] \]</pre><p>And <code class="m-code">$ \hat q $</code> is how quaternion is denoted. A green formula should have the CSS class applied:</p><pre class="m-code m-text m-success">\[ \pi^2 \]</pre><p>A yellow <code class="m-code m-text m-warning">$ \Sigma $</code> inline formula as well.</p>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
diff --git a/documentation/test_doxygen/contents_math_code_fallback/index.html b/documentation/test_doxygen/contents_math_code_fallback/index.html
new file mode 100644
index 00000000..c69cfe88
--- /dev/null
+++ b/documentation/test_doxygen/contents_math_code_fallback/index.html
@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          My Project
+        </h1>
+<p>Here&#x27;s a block formula:</p><pre class="m-code">\[
+    \hat q = [\boldsymbol 0, 1] + \epsilon [\frac{\boldsymbol v}{2}, 0]
+\]</pre><p>And <code class="m-code">$ \hat q $</code> is how quaternion is denoted. A green formula should have the CSS class applied:</p><pre class="m-code m-text m-success">\[
+    \pi^2
+\]</pre><p>A yellow <code class="m-code m-text m-warning">$ \Sigma $</code> inline formula as well.</p>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
diff --git a/documentation/test_doxygen/contents_math_code_fallback/input.dox b/documentation/test_doxygen/contents_math_code_fallback/input.dox
new file mode 100644
index 00000000..433eec12
--- /dev/null
+++ b/documentation/test_doxygen/contents_math_code_fallback/input.dox
@@ -0,0 +1,19 @@
+/** @mainpage
+
+Here's a block formula:
+
+@f[
+    \hat q = [\boldsymbol 0, 1] + \epsilon [\frac{\boldsymbol v}{2}, 0]
+@f]
+
+And @f$ \hat q @f$ is how quaternion is denoted. A green formula should have
+the CSS class applied:
+
+@m_class{m-text m-success}
+
+@f[
+    \pi^2
+@f]
+
+A yellow @m_class{m-text m-warning} @f$ \Sigma @f$ inline formula as well.
+*/
diff --git a/documentation/test_doxygen/test_contents.py b/documentation/test_doxygen/test_contents.py
index e88d0968..0bddd3b3 100644
--- a/documentation/test_doxygen/test_contents.py
+++ b/documentation/test_doxygen/test_contents.py
@@ -164,6 +164,16 @@ class Math(IntegrationTestCase):
         with self.assertRaises(subprocess.CalledProcessError) as context:
             self.run_doxygen(wildcard='error.xml')
 
+class MathCodeFallback(IntegrationTestCase):
+    def test(self):
+        self.run_doxygen(wildcard='indexpage.xml')
+
+        # Doxygen 1.9.8+ (or maybe earlier? 1.9.1 not yet) changes the spacing,
+        if parse_version(doxygen_version()) >= parse_version("1.9.8"):
+            self.assertEqual(*self.actual_expected_contents('index.html'))
+        else:
+            self.assertEqual(*self.actual_expected_contents('index.html', 'index-191.html'))
+
 class MathCached(IntegrationTestCase):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
diff --git a/documentation/test_doxygen/test_doxyfile.py b/documentation/test_doxygen/test_doxyfile.py
index 022d1f25..e91b717d 100644
--- a/documentation/test_doxygen/test_doxyfile.py
+++ b/documentation/test_doxygen/test_doxyfile.py
@@ -77,6 +77,7 @@ class Doxyfile(unittest.TestCase):
         'M_CODE_FILTERS_PRE': {},
         'M_CODE_FILTERS_POST': {},
         'M_MATH_CACHE_FILE': 'm.math.cache',
+        'M_MATH_RENDER_AS_CODE': False,
 
         'SEARCH_DISABLED': False,
         'SEARCH_DOWNLOAD_BINARY': False,