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

[via lldb-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-lldb

Author: Nerixyz (Nerixyz)

<details>
<summary>Changes</summary>

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

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


3 Files Affected:

- (modified) lldb/docs/_ext/build_include.py (+1-1) 
- (modified) lldb/docs/_ext/lldb_setting.py (+1-20) 
- (modified) lldb/scripts/gen-property-docs-from-json.py (+10-3) 


``````````diff
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..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")
 
@@ -136,7 +143,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 +152,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)
 

``````````

</details>


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