From 719d4509c05d379a6ff55ed3d9a9742f1fd57c96 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dennis=20Gl=C3=A4ser?= <dennis.glaeser@iws.uni-stuttgart.de>
Date: Wed, 22 Mar 2023 16:51:29 +0100
Subject: [PATCH] [doxygen] pass all markdown files through filter
---
doc/doxygen/Doxylocal | 4 +-
doc/doxygen/markdown-readme-header-filter.py | 57 +++++++++++++-------
2 files changed, 39 insertions(+), 22 deletions(-)
diff --git a/doc/doxygen/Doxylocal b/doc/doxygen/Doxylocal
index 6e57507359..0280bef144 100644
--- a/doc/doxygen/Doxylocal
+++ b/doc/doxygen/Doxylocal
@@ -18,8 +18,8 @@ TOC_INCLUDE_HEADINGS = 4
# 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 = *README.md="python3 @srcdir@/markdown-readme-header-filter.py" \
- *.md="perl -0777 -p @srcdir@/markdown-math-filter.pl"
+FILTER_PATTERNS = *README.md="python3 @srcdir@/markdown-readme-header-filter.py -p Introduction -f" \
+ *.md="python3 @srcdir@/markdown-readme-header-filter.py -f"
FILE_PATTERNS = *.md,*.cc,*.hh
diff --git a/doc/doxygen/markdown-readme-header-filter.py b/doc/doxygen/markdown-readme-header-filter.py
index f18567fcb9..e7ba6487b4 100644
--- a/doc/doxygen/markdown-readme-header-filter.py
+++ b/doc/doxygen/markdown-readme-header-filter.py
@@ -1,35 +1,52 @@
#!/usr/bin/python3
-# Process the main readme (GitLab Markdown) to render properly with doxygen
-# -> Prepend level-1 header (doxygen will use this as caption for the section)
-# and turn all level-1 headers into level-2 ones. These will then be sub-sections.
-# -> Add labels to headers such that section links within the readme work.
-
-import sys
import string
+import argparse
+import subprocess
+from os.path import join, dirname, abspath
-def _remove_punctuations(text: str) -> str:
- return "".join(filter(lambda c: c not in string.punctuation, text))
-
-
-def _modify_header_level(line: str) -> str:
- is_level_one_header = line.startswith("# ")
- return f"#{line}" if is_level_one_header else f"{line}"
+def _filter_characters(text: str) -> str:
+ return "".join(filter(lambda c: c not in string.punctuation and c not in string.digits, text))
def _add_header_label(line: str) -> str:
if not line.startswith("#"):
return line
line = line.rstrip("\n")
- label = _remove_punctuations(line)
+ label = _filter_characters(line)
label = label.strip(" ").replace(" ", "-").lower()
return f"{line} {{#{label}}}\n"
-assert len(sys.argv) > 1
-lines = ["# Introduction\n"]
-with open(sys.argv[1]) as readme:
- for line in readme:
- lines.append(_add_header_label(_modify_header_level(line)))
-print("".join(lines))
+def _invoke_and_retrieve_output(cmd) -> str:
+ return subprocess.run(cmd, capture_output=True, text=True).stdout
+
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser(description="Process markdown files to be consumed by Doxygen")
+ parser.add_argument("-f", "--file", required=True, help="The markdown file to be processed")
+ parser.add_argument(
+ "-p",
+ "--prepend-header",
+ required=False,
+ help="Adds the given header at the top of the file"
+ )
+ args = vars(parser.parse_args())
+
+ # Invoke math filter to translate GitLab flavoured math to such supported by Doxygen
+ math_conversion_script = join(dirname(abspath(__file__)), "markdown-math-filter.pl")
+ result = _invoke_and_retrieve_output(["perl", "-0777", "-p", math_conversion_script, args["file"]])
+
+ # (maybe) prepend the given header
+ if args["prepend_header"]:
+ result = f"# {args['prepend_header']}\n\n{result}"
+
+ # Give all headers anchors (labels) s.t. doxygen cross-linking works
+ # correctly (may be fixed in the most recent Doxygen version)
+ result_lines = []
+ for line in result.split("\n"):
+ result_lines.append(_add_header_label(line))
+
+ # Print the final result for Doxygen to pick it up
+ print("\n".join(result_lines))
--
GitLab