[lldb] Enable support for Markdown documentation pages

[DavidSpickett]

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 8b95bd3 but that got reverted. That did this in a different way but 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.

[llvmbot]

@llvm/pr-subscribers-lldb

Author: David Spickett (DavidSpickett)

Changes

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 8b95bd3 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.

---

Full diff: https://github.com/llvm/llvm-project/pull/89716.diff

1 Files Affected:

• (modified) lldb/docs/conf.py (+21)

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.

[DavidSpickett]

This will be used by #89718, but I would like to land this PR first to flush out any bot config problems.

[JDevlieghere]

LGTM