documentation/doxygen: add an ability to run filters on code.

Finally I'm able to generate Magnum docs without a hastily patched
m.css to convert color literals to color swatches. Ugh this took ages.

diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst
index 7329c8760a82013c361f257a4a0b969aac8d5118..166d5ca9e8d6ebff567df738427a2bd995f0d1bd 100644 (file)
--- a/doc/documentation/doxygen.rst
+++ b/doc/documentation/doxygen.rst
@@ -413,10 +413,19 @@ Variable                            Description
                                     for more information.
 :py:`M_MATH_CACHE_FILE`             File to cache rendered math formulas. If
                                     not set, ``m.math.cache`` file in the
-                                    output directory is used. Old cached output
-                                    is periodically pruned and new formulas
-                                    added to the file. Set it empty to disable
-                                    caching.
+                                    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_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>`.
+                                    Note that due to the limitations of Doxygen
+                                    markup, named filters are not supported.
+:py:`M_CODE_FILTERS_POST: Dict`     Filters to apply after 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>`.
+                                    Note that due to the limitations of Doxygen
+                                    markup, named filters are not supported.
 =================================== ===========================================
 
 Note that namespace, directory and page lists are always fully expanded as

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 4e82f243cc582e81eb90a9f917971955f33880e3..e8b44c24cd46956333a51c71d96f23a739dfb555 100755 (executable)
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -120,6 +120,8 @@ default_config = {
     'CLASS_INDEX_EXPAND_INNER': False,
 
     'M_MATH_CACHE_FILE': 'm.math.cache',
+    'M_CODE_FILTERS_PRE': {},
+    'M_CODE_FILTERS_POST': {},
 
     'SEARCH_DISABLED': False,
     'SEARCH_DOWNLOAD_BINARY': False,
@@ -1240,10 +1242,19 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
             else:
                 formatter = HtmlFormatter(nowrap=True)
 
+            # Apply a global pre filter, if any
+            filter = state.config['M_CODE_FILTERS_PRE'].get(lexer.name)
+            if filter: code = filter(code)
+
             highlighted = highlight(code, lexer, formatter).rstrip()
             # Strip whitespace around if inline code, strip only trailing
             # whitespace if a block
             if not code_block: highlighted = highlighted.lstrip()
+
+            # Apply a global post filter, if any
+            filter = state.config['M_CODE_FILTERS_POST'].get(lexer.name)
+            if filter: highlighted = filter(highlighted)
+
             out.parsed += '<{0} class="{1}{2}">{3}</{0}>'.format(
                 'pre' if code_block else 'code',
                 class_,

diff --git a/documentation/test_doxygen/__init__.py b/documentation/test_doxygen/__init__.py
index 7b94f1d4f6484426b76ea3805a05a69435e9c32b..f4d8724a1b646db2164d87e5a778b0d087d59e30 100644 (file)
--- a/documentation/test_doxygen/__init__.py
+++ b/documentation/test_doxygen/__init__.py
@@ -66,8 +66,8 @@ class BaseTestCase(unittest.TestCase):
     def setUp(self):
         if os.path.exists(os.path.join(self.path, 'html')): shutil.rmtree(os.path.join(self.path, 'html'))
 
-    def run_doxygen(self, templates=default_templates, wildcard=default_wildcard, index_pages=default_index_pages):
-        state = State(copy.deepcopy(default_config))
+    def run_doxygen(self, templates=default_templates, wildcard=default_wildcard, index_pages=default_index_pages, config={}):
+        state = State({**copy.deepcopy(default_config), **config})
         parse_doxyfile(state, os.path.join(self.path, 'Doxyfile'))
         run(state, templates=templates, wildcard=wildcard, index_pages=index_pages, sort_globbed_files=True)
 

diff --git a/documentation/test_doxygen/contents_code_filters/Doxyfile b/documentation/test_doxygen/contents_code_filters/Doxyfile
new file mode 100644 (file)
index 0000000..0797976
--- /dev/null
+++ b/documentation/test_doxygen/contents_code_filters/Doxyfile
@@ -0,0 +1,14 @@
+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

diff --git a/documentation/test_doxygen/contents_code_filters/index.html b/documentation/test_doxygen/contents_code_filters/index.html
new file mode 100644 (file)
index 0000000..c8d5dc8
--- /dev/null
+++ b/documentation/test_doxygen/contents_code_filters/index.html
@@ -0,0 +1,33 @@
+<!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>Adding typographically correct spaces before and a color swatch after &mdash; and for inline as well: <code class="m-code"><span class="nt">p</span> <span class="p">{</span> <span class="k">color</span><span class="p">:</span> <span class="mh">#ff3366<span class="m-code-color" style="background-color: #ff3366;"></span></span><span class="p">;</span> <span class="p">}</span></code></p><pre class="m-code"><span class="nt">p</span> <span class="p">{</span>
+    <span class="k">color</span><span class="p">:</span> <span class="mh">#ff3366<span class="m-code-color" style="background-color: #ff3366;"></span></span><span class="p">;</span>
+<span class="p">}</span></pre>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>

diff --git a/documentation/test_doxygen/contents_code_filters/input.dox b/documentation/test_doxygen/contents_code_filters/input.dox
new file mode 100644 (file)
index 0000000..deb634e
--- /dev/null
+++ b/documentation/test_doxygen/contents_code_filters/input.dox
@@ -0,0 +1,14 @@
+/** @mainpage
+
+Adding typographically correct spaces before and a color swatch after --- and
+for inline as well: @code{.css} p{ color:#ff3366; } @endcode
+
+@code{.css}
+
+    p{
+        color:#ff3366;
+    }
+
+@endcode
+
+*/

diff --git a/documentation/test_doxygen/test_contents.py b/documentation/test_doxygen/test_contents.py
index ffaf3a1dca9dc23b2086fb66bbae6df2841d3f83..df658017e984dee4c36addadac8a9867b0563e4e 100644 (file)
--- a/documentation/test_doxygen/test_contents.py
+++ b/documentation/test_doxygen/test_contents.py
@@ -359,3 +359,21 @@ class Htmlinclude(IntegrationTestCase):
     def test_warnings(self):
         self.run_doxygen(wildcard='warnings.xml')
         self.assertEqual(*self.actual_expected_contents('warnings.html'))
+
+_css_colors_src = re.compile(r"""<span class="mh">#(?P<hex>[0-9a-f]{6})</span>""")
+_css_colors_dst = r"""<span class="mh">#\g<hex><span class="m-code-color" style="background-color: #\g<hex>;"></span></span>"""
+
+def _add_color_swatch(str):
+    return _css_colors_src.sub(_css_colors_dst, str)
+
+class CodeFilters(IntegrationTestCase):
+    def test(self):
+        self.run_doxygen(wildcard='indexpage.xml', config={
+            'M_CODE_FILTERS_PRE': {
+                'CSS': lambda str: str.replace(':', ': ').replace('{', ' {'),
+            },
+            'M_CODE_FILTERS_POST': {
+                'CSS': _add_color_swatch,
+            }
+        })
+        self.assertEqual(*self.actual_expected_contents('index.html'))

diff --git a/documentation/test_doxygen/test_doxyfile.py b/documentation/test_doxygen/test_doxyfile.py
index 62c6d00ffa81b68fedbf4a176fd36565f5322717..252798b643e929f429d2325933e3446329416476 100644 (file)
--- a/documentation/test_doxygen/test_doxyfile.py
+++ b/documentation/test_doxygen/test_doxyfile.py
@@ -70,6 +70,8 @@ class Doxyfile(unittest.TestCase):
         'CLASS_INDEX_EXPAND_INNER': False,
         'FILE_INDEX_EXPAND_LEVELS': 1,
 
+        'M_CODE_FILTERS_PRE': {},
+        'M_CODE_FILTERS_POST': {},
         'M_MATH_CACHE_FILE': 'm.math.cache',
 
         'SEARCH_DISABLED': False,