[Lldb-commits] [lldb] [lldb] Enable support for Markdown documentation pages (PR #89716)

[David Spickett via lldb-commits]

https://github.com/DavidSpickett created https://github.com/llvm/llvm-project/pull/89716

RST is powerful but usually too powerful for 90% of what we need it for. Markdown is easier to edit and can be previewed easily without building the entire website.

This copies what llvm does already, making myst_parser optional if you only want man pages.

Previously we had Markdown enabled in 8b95bd3310c126e76e0714bea6003a9b1aa739fb but that got reverted. That did this in a different way, I've gone with the standard llvm set this time.

I intend the first Markdown pages to be the remote protocol extension docs, as they are not in any set format right now.

>From 9067fdfa42b0ba59119d910b49cf3147d57310dc Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Mon, 22 Apr 2024 09:04:42 +0100
Subject: [PATCH] [lldb] Enable support for Markdown documentation pages

RST is powerful but usually too powerful for 90% of what we need
it for. Markdown is easier to edit and can be previewed easily
without building the entire website.

This copies what llvm does already, making myst_parser optional
if you only want man pages.

Previously we had Markdown enabled in 8b95bd3310c126e76e0714bea6003a9b1aa739fb
but that got reverted. That did this in a different way,
I've gone with the standard llvm set this time.

I intend the first Markdown pages to be the remote protocol
extension docs, as they are not in any set format right now.
---
 lldb/docs/conf.py | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/lldb/docs/conf.py b/lldb/docs/conf.py
index ec7f93710ab6f2..27a1cd7c3c31ac 100644
--- a/lldb/docs/conf.py
+++ b/lldb/docs/conf.py
@@ -13,6 +13,9 @@
 import sys, os, re, shutil
 from datetime import date
 
+# Add path for llvm_slug module.
+sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "llvm", "docs")))
+
 building_man_page = tags.has("builder-man")
 
 # For the website we need to setup the path to the generated LLDB module that
@@ -42,6 +45,23 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ["sphinx.ext.todo", "sphinx.ext.mathjax", "sphinx.ext.intersphinx"]
 
+# When building man pages, we do not use the markdown pages,
+# So, we can continue without the myst_parser dependencies.
+# Doing so reduces dependencies of some packaged llvm distributions.
+try:
+    import myst_parser
+
+    extensions.append("myst_parser")
+except ImportError:
+    if not tags.has("builder-man"):
+        raise
+
+# Automatic anchors for markdown titles
+from llvm_slug import make_slug
+
+myst_heading_anchors = 6
+myst_heading_slug_func = make_slug
+
 autodoc_default_options = {"special-members": True}
 
 # Unless we only generate the basic manpage we need the plugin for generating
@@ -69,6 +89,7 @@
 # The suffix of source filenames.
 source_suffix = {
     ".rst": "restructuredtext",
+    ".md": "markdown",
 }
 
 # The encoding of source files.