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.spick...@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.
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
