From d903b9df43c62300972a05ecf9624d493cf1fd1a Mon Sep 17 00:00:00 2001
From: Timo Koch <timokoch@math.uio.no>
Date: Thu, 16 Mar 2023 08:39:03 +0000
Subject: [PATCH] [doxygen] Add filter to convert GitLab math to doxygen math
in markdown
---
doc/doxygen/Doxylocal | 5 ++
doc/doxygen/markdown-math-filter.pl | 122 ++++++++++++++++++++++++++++
2 files changed, 127 insertions(+)
create mode 100755 doc/doxygen/markdown-math-filter.pl
diff --git a/doc/doxygen/Doxylocal b/doc/doxygen/Doxylocal
index a260784a90..4a6f900f73 100644
--- a/doc/doxygen/Doxylocal
+++ b/doc/doxygen/Doxylocal
@@ -11,6 +11,11 @@ INPUT += @srcdir@/mainpage.txt \
@top_srcdir@/dumux \
@srcdir@/extradoc/parameterlist.txt
+# Input filters run over content before it is parsed by Doxygen.
+# - Format markdown math for Doxygen. See the documentation in
+# `markdown-math-filter.pl` for details.
+FILTER_PATTERNS = *.md="perl -0777 -p @srcdir@/markdown-math-filter.pl"
+
FILE_PATTERNS = *.md,*.cc,*.hh
EXCLUDE += @top_srcdir@/dumux/io/format/fmt
diff --git a/doc/doxygen/markdown-math-filter.pl b/doc/doxygen/markdown-math-filter.pl
new file mode 100755
index 0000000000..c764ff399d
--- /dev/null
+++ b/doc/doxygen/markdown-math-filter.pl
@@ -0,0 +1,122 @@
+#!/usr/bin/env perl
+#
+#
+# Doxygen filter to format markdown math for Doxygen
+#
+# In Doxygen documentation, including markdown files or Jupyter notebooks that
+# get converted to markdown, you can use standard $...$ syntax for inline math,
+# and $$...$$ or ```math...``` syntax for display-style math.
+#
+# This is needed until Doxygen adds support for markdown-style math, see
+# https://github.com/doxygen/doxygen/issues/8009.
+#
+# Based on the original by Simulating eXtreme Spacetimes Collaboration
+# distributed under the MIT License as specified below:
+#
+# ==============================================================================
+# SpECTRE Release License
+# ==============================================================================
+#
+# Copyright 2017 - 2023 Simulating eXtreme Spacetimes Collaboration
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# This is added to the original to allow for $$...$$ for display math
+# Wrap inline math in \f$...\f$
+# - Match code blocks (wrapped in ``` or \code...\endcode) and inline code
+# (wrapped in ` or ``), and print them directly to the output with no changes.
+# - Match display math blocks (wrapped in \f[...\f], \f{...\f}, or
+# \begin...\end), and print them directly to the output with no changes.
+# - Replace $$...$$ by \f{equation}{...\f}.
+# - The '?' makes the pattern match lazily, i.e., match as few characters as
+# possible.
+# - Modifiers:
+# s: Allow '.' to match newlines
+# g: Replace all occurrences
+# e: Evaluate replacement as perl code, so we can switch between
+# replacements depending on the matched alternative, using the '//'
+# (definedness) operator.
+# x: Ignore spaces for better readability
+s{ (```.*?```)
+ | (``.*?``)
+ | (`.*?`)
+ | (\\code.*?\\endcode)
+ | (\\f\[.*?\\f\])
+ | (\\f\{.*?\\f\})
+ | (\\begin\{(.*?)\}(.*?)\\end\{\6\})
+ | \${2}(.*?)\${2}
+}{ $1 // $2 // $3 // $4 // $5 // $6 // $7 // "\\begin\{align\}$10\\end{align}" }sgex;
+
+# This is added to the original to allow for $`...`$ for inline math (GitLab flavor)
+# Wrap inline math in \f$...\f$
+# - Match code blocks (wrapped in ``` or \code...\endcode) and inline code
+# (wrapped in ` or ``), and print them directly to the output with no changes.
+# - Match display math blocks (wrapped in \f[...\f], \f{...\f}, or
+# \begin...\end), and print them directly to the output with no changes.
+# - Replace $...$ by \f$...\f$, unless already preceded by '\f$'.
+s{ (```.*?```)
+ | (``.*?``)
+ | (`.*?`)
+ | (\\code.*?\\endcode)
+ | (\\f\[.*?\\f\])
+ | (\\f\{.*?\\f\})
+ | (\\begin\{(.*?)\}(.*?)\\end\{\6\})
+ | (?<!\\f)\$`(.*?)`\$
+}{ $1 // $2 // $3 // $4 // $5 // $6 // $7 // "\\f\$$10\\f\$" }sgex;
+
+# Wrap inline math in \f$...\f$
+# - Match code blocks (wrapped in ``` or \code...\endcode) and inline code
+# (wrapped in ` or ``), and print them directly to the output with no changes.
+# - Match display math blocks (wrapped in \f[...\f], \f{...\f}, or
+# \begin...\end), and print them directly to the output with no changes.
+# - Replace $...$ by \f$...\f$, unless already preceded by '\f$'.
+s{ (```.*?```)
+ | (``.*?``)
+ | (`.*?`)
+ | (\\code.*?\\endcode)
+ | (\\f\[.*?\\f\])
+ | (\\f\{.*?\\f\})
+ | (\\begin\{(.*?)\}(.*?)\\end\{\6\})
+ | (?<!\\f)\$(.*?)\$
+}{ $1 // $2 // $3 // $4 // $5 // $6 // $7 // "\\f\$$10\\f\$" }sgex;
+
+# This is added to the original to allow for ```math...``` for display math (GitLab flavor)
+# Wrap display math in \f{equation}{ ... \f}
+# - Replace ```math...``` with \f{equation}{...\f}.
+# - Match code blocks (wrapped in ``` or \code...\endcode) and Doxygen-style
+# display equations formatted either \f[...\f] or \f{...}{...\f}, and print
+# them to the output with no changes.
+s{ ```math(.*?)```
+ | (```.*?```)
+ | (\\code.*?\\endcode)
+ | (\\f\[.*?\\f\])
+ | (\\f\{.*?\\f\})
+}{ $2 // "\\f\{align\}\{$1\\f\}" // $3 // $4 // $5 }sgex;
+
+# Wrap display math in \f{equation}{ ... \f}
+# - Match code blocks (wrapped in ``` or \code...\endcode) and Doxygen-style
+# display equations formatted either \f[...\f] or \f{...}{...\f}, and print
+# them to the output with no changes.
+# - Replace \begin{...}...\end{...} with \f{...}{...\f}.
+s{ (```.*?```)
+ | (\\code.*?\\endcode)
+ | (\\f\[.*?\\f\])
+ | (\\f\{.*?\\f\})
+ | \\begin\{(.*?)\}(.*?)\\end\{\5\}
+}{ $1 // $2 // $3 // $4 // "\\f\{$5\}\{$6\\f\}" }sgex;
--
GitLab