better public interface and doxygen

1 files changed, 24 insertions, 0 deletions

diff --git a/docs/doxygen_filter.py b/docs/doxygen_filter.py
new file mode 100644
index 0000000..ed6e6e8
--- /dev/null
+++ b/docs/doxygen_filter.py
@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""Resolve repository source links to Doxygen reference/example pages.
+
+Markdown keeps ordinary relative links for repository and installed-document
+readers. Doxygen gets @ref links so its standalone HTML has no source-tree URLs.
+"""
+
+from pathlib import Path
+import re
+import sys
+
+text = Path(sys.argv[1]).read_text(encoding="utf-8")
+
+
+def reference(match):
+    label, target = match.groups()
+    if target.startswith("../include/yasl/") and target.endswith(".h"):
+        return f"[{label}](@ref {Path(target).name})"
+    if target.startswith("../examples/") and target.endswith(".c"):
+        return f"[{label}](@ref {Path(target).name})"
+    return match.group(0)
+
+
+sys.stdout.write(re.sub(r"\[([^\]]+)\]\(([^)]+)\)", reference, text))