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

[via lldb-commits]

Author: Nerixyz
Date: 2026-04-15T16:03:18+02:00
New Revision: b9077c8e6aaa6c23c0735977fb52a264c6709071

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

LOG: [lldb][Docs] Fix presentation of some default values (#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).

Added: 
    

Modified: 
    lldb/docs/_ext/build_include.py
    lldb/docs/_ext/lldb_setting.py
    lldb/scripts/gen-property-docs-from-json.py

Removed: 
    


################################################################################
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/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 e3fd832e6a5c2..e7de4ea2f4120 100644
--- a/lldb/scripts/gen-property-docs-from-json.py
+++ b/lldb/scripts/gen-property-docs-from-json.py
@@ -2,6 +2,7 @@
 from typing import TypedDict, Union, Optional, TextIO, NotRequired
 from dataclasses import dataclass
 import json
+import re
 
 
 PropertyDef = TypedDict(
@@ -76,6 +77,14 @@ def append_property(tree: PropertyTree, prop: Property):
     subtree.items[prop.name] = prop
 
 
+def wrap_inline_code(text: str):
+    n_backticks = max([len(s) for s in re.findall("`+", text)], default=0)
+    fence = "`" * (n_backticks + 1)
+    if text.startswith("`") or text.endswith("`"):
+        text = f" {text} "
+    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 +92,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")
 
@@ -136,7 +145,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 +154,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)