From e18ef90566d27e411b7880f4661cc57f761f0e7e Mon Sep 17 00:00:00 2001
From: Rob Cowsill <42620235+rcowsill@users.noreply.github.com>
Date: Wed, 28 Apr 2021 16:21:24 +0100
Subject: [PATCH] [CI:DOCS] Improve titles of command HTML pages

When building Sphinx HTML docs, preprocess markdown files and convert
pandoc-style title lines into recommonmark eval_rst blocks

This gives command HTML pages the same title as the equivalent manpage

Fixes: containers/podman.io#385

Signed-off-by: Rob Cowsill <42620235+rcowsill@users.noreply.github.com>
---
 docs/source/conf.py | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 883e1240e0..52869baf49 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -14,6 +14,8 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import re
+from recommonmark.transform import AutoStructify
 
 # -- Project information -----------------------------------------------------
 
@@ -59,3 +61,27 @@
 ]
 
 # -- Extension configuration -------------------------------------------------
+
+def convert_markdown_title(app, docname, source):
+    # Process markdown files only
+    docpath = app.env.doc2path(docname)
+    if docpath.endswith(".md"):
+        # Convert pandoc title line into eval_rst block for recommonmark
+        source[0] = re.sub(
+            r"^% (.*)",
+            r"```eval_rst\n.. title:: \g<1>\n```",
+            source[0])
+
+
+def setup(app):
+    app.connect("source-read", convert_markdown_title)
+
+    app.add_config_value(
+        "recommonmark_config", {
+            "enable_eval_rst": True,
+            "enable_auto_doc_ref": False,
+            "enable_auto_toc_tree": False,
+            "enable_math": False,
+            "enable_inline_math": False,
+        }, True)
+    app.add_transform(AutoStructify)