From 8050339ca1a644369512be49a7b17dccafe258ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Wed, 15 Jul 2020 18:00:26 +0200
Subject: [PATCH] doc: allow ignoring portions of code snippets.

Ugh finally I'm able to write docs without unimportant boilerplate.
---
 doc/conf.py | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/doc/conf.py b/doc/conf.py
index 257c669de..131bf8f71 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -41,6 +41,28 @@ VERSION_LABELS = True
 _magnum_colors_src = re.compile(r"""<span class="mh">0x(?P<hex>[0-9a-f]{6})(?P<alpha>[0-9a-f]{2})?(?P<literal>_s?rgba?f?)</span>""")
 _magnum_colors_dst = r"""<span class="mh">0x\g<hex>\g<alpha>\g<literal><span class="m-code-color" style="background-color: #\g<hex>;"></span></span>"""
 
+# Code wrapped in DOXYGEN_IGNORE() will get replaced by an (Unicode) ellipsis
+# in the output. In order to make the same code compilable, add
+#
+#   #define DOXYGEN_IGNORE(...) __VA_ARGS__
+#
+# to the snippet code
+def _doxygen_ignore(code: str):
+    while 'DOXYGEN_IGNORE(' in code:
+        i = code.index('DOXYGEN_IGNORE(')
+        depth = 1
+        for j in range(i + len('DOXYGEN_IGNORE('), len(code)):
+            if code[j] == '(': depth += 1
+            elif code[j] == ')': depth -= 1
+            if depth == 0: break
+        assert depth == 0, "unmatched DOXYGEN_IGNORE() parentheses in %s" % code
+        code = code[:i] + '…' + code[j+1:]
+    return code
+
+M_CODE_FILTERS_PRE = {
+    'C++': _doxygen_ignore
+}
+
 M_CODE_FILTERS_POST = {
     'C++': lambda str: _magnum_colors_src.sub(_magnum_colors_dst, str)
 }