[Lldb-commits] [lldb] [lldb][Docs] Fix presentation of some default values (PR #192239)

[via lldb-commits]

https://github.com/Nerixyz created https://github.com/llvm/llvm-project/pull/192239

There were two bugs with the display of default values:

1. If a default value contains a backtick, that would render incorrectly. For example [`disassembly-format`](https://lldb.llvm.org/use/settings.html#disassembly-format). Fixed by doing the wrapping when we generate the Markdown instead of when parsing the directive. MyST will already parse the content of the directive as Markdown. We can escape backticks inside the string by changing the fence. Markdown can take any number of backticks at the start as long as they match the amount at the end ([spec](https://spec.commonmark.org/0.31.2/#code-spans)).
2. When the docs were built on Windows, UTF-8 was not correctly picked up, because the default encoding isn't utf8 there. [`separator`](https://lldb.llvm.org/use/settings.html#separator) was one example (renders correctly on the Website but not on my machine).

Preview updated at: https://nerixyz.github.io/test-gh-pages/use/settings.html

>From f848e4045bd1b6489db7a9a01efba0da83bb84a2 Mon Sep 17 00:00:00 2001
From: Nerixyz <nerixdev at outlook.de>
Date: Wed, 15 Apr 2026 13:02:10 +0200
Subject: [PATCH 1/2] fix: wrap code when generating documentation

---
 lldb/docs/_ext/build_include.py             | 2 +-
 lldb/scripts/gen-property-docs-from-json.py | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/lldb/docs/_ext/build_include.py b/lldb/docs/_ext/build_include.py
index 40be3073605f8..ee8ba6f797410 100644
--- a/lldb/docs/_ext/build_include.py
+++ b/lldb/docs/_ext/build_include.py
@@ -21,7 +21,7 @@ class BuildInclude(Directive):
     def run(self):
         path = directives.path(self.arguments[0])
         path = utils.relative_path(None, Path(os.environ["LLDB_BUILD_DIR"]) / path)
-        with open(path) as f:
+        with open(path, encoding="utf-8") as f:
             rawtext = f.read()
         include_lines = statemachine.string2lines(
             rawtext, self.state.document.settings.tab_width, convert_whitespace=True
diff --git a/lldb/scripts/gen-property-docs-from-json.py b/lldb/scripts/gen-property-docs-from-json.py
index e3fd832e6a5c2..e84955d2b372f 100644
--- a/lldb/scripts/gen-property-docs-from-json.py
+++ b/lldb/scripts/gen-property-docs-from-json.py
@@ -136,7 +136,7 @@ def main():
 
     root = PropertyTree(items={})
     for input in args.inputs:
-        with open(input) as f:
+        with open(input, encoding="utf-8") as f:
             properties: dict[str, PropertyDef] = json.load(f)
         for key, prop in properties.items():
             if key.startswith("!"):
@@ -145,7 +145,7 @@ def main():
                 continue  # not a property
             append_property(root, Property(prop))
 
-    with open(args.output, "w") as f:
+    with open(args.output, "w", encoding="utf-8") as f:
         f.write(HEADER)
         print_tree(f, 0, "", "", root)
 

>From fae63cbc5a4054d4aef16d25a209525272a79c0e Mon Sep 17 00:00:00 2001
From: Nerixyz <nerixdev at outlook.de>
Date: Wed, 15 Apr 2026 13:03:37 +0200
Subject: [PATCH 2/2] fix: specify utf-8 encoding when opening files

---
 lldb/docs/_ext/lldb_setting.py              | 21 +--------------------
 lldb/scripts/gen-property-docs-from-json.py |  9 ++++++++-
 2 files changed, 9 insertions(+), 21 deletions(-)

diff --git a/lldb/docs/_ext/lldb_setting.py b/lldb/docs/_ext/lldb_setting.py
index 331789633e9da..1d6171ab482e4 100644
--- a/lldb/docs/_ext/lldb_setting.py
+++ b/lldb/docs/_ext/lldb_setting.py
@@ -8,20 +8,6 @@
 import llvm_slug
 
 
-class LiteralField(Field):
-    """A field that wraps the content in <code></code>"""
-
-    def make_field(self, types, domain, item, env=None, inliner=None, location=None):
-        fieldarg, content = item
-        fieldname = nodes.field_name("", self.label)
-        if fieldarg:
-            fieldname += nodes.Text(" ")
-            fieldname += nodes.Text(fieldarg)
-
-        fieldbody = nodes.field_body("", nodes.literal("", "", *content))
-        return nodes.field("", fieldname, fieldbody)
-
-
 # Example:
 # ```{lldbsetting} dwim-print-verbosity
 # :type: "enum"
@@ -38,12 +24,7 @@ class LLDBSetting(ObjectDescription):
         "type": directives.unchanged,
     }
     doc_field_types = [
-        LiteralField(
-            "default",
-            label="Default",
-            has_arg=False,
-            names=("default",),
-        ),
+        Field("default", label="Default", has_arg=False, names=("default",)),
         GroupedField("enum", label="Enumerations", names=("enum",)),
     ]
 
diff --git a/lldb/scripts/gen-property-docs-from-json.py b/lldb/scripts/gen-property-docs-from-json.py
index e84955d2b372f..da7d0fc0f5f31 100644
--- a/lldb/scripts/gen-property-docs-from-json.py
+++ b/lldb/scripts/gen-property-docs-from-json.py
@@ -76,6 +76,13 @@ def append_property(tree: PropertyTree, prop: Property):
     subtree.items[prop.name] = prop
 
 
+def wrap_inline_code(text: str):
+    fence = "`"
+    if "`" in text:
+        fence = "``"
+    return f"{fence}{text}{fence}"
+
+
 def print_property(f: TextIO, path: str, property: Property):
     # Invoke lldbsetting directive (lldb/docs/_ext/lldb_setting.py)
     f.write(f"```{{lldbsetting}} {path}\n")
@@ -83,7 +90,7 @@ def print_property(f: TextIO, path: str, property: Property):
     f.write(property.description)
     f.write("\n\n")
     if property.default:
-        f.write(f":default: {property.default}\n")
+        f.write(f":default: {wrap_inline_code(property.default)}\n")
     # FIXME: add enumerations (":enum {name}: {description}")
     f.write("```\n")