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

[via lldb-commits]

Author: David Spickett
Date: 2024-04-24T09:08:31+01:00
New Revision: 62db43497fb019d0ac0677ae0c9ea2eba136b230

URL: https://github.com/llvm/llvm-project/commit/62db43497fb019d0ac0677ae0c9ea2eba136b230
DIFF: https://github.com/llvm/llvm-project/commit/62db43497fb019d0ac0677ae0c9ea2eba136b230.diff

LOG: [lldb] Enable support for Markdown documentation pages (#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 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.

Added: 
    

Modified: 
    lldb/docs/conf.py

Removed: 
    


################################################################################
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.