[LLDB][Docs] List available settings

Author: Nerixyz

lldb/docs/CMakeLists.txt

@@ -36,6 +36,12 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
 
     add_dependencies(lldb-python-doc-package swig_wrapper_python lldb-python)
 
+    add_custom_target(lldb-doc-autogen
+      COMMAND $<TARGET_FILE:lldb-test> generate-docs "--output-dir=${CMAKE_CURRENT_LIST_DIR}/use"
+      COMMENT "Generating settings documentation."
+    )
+    add_dependencies(lldb-doc-autogen lldb-test)
+
     # FIXME: Don't treat Sphinx warnings as errors. The files generated by
     # automodapi are full of warnings (partly caused by SWIG, our documentation
     # and probably also automodapi itself), so those warnings need to be fixed
@@ -51,7 +57,7 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
     add_custom_target(clean-lldb-html COMMAND "${CMAKE_COMMAND}" -E
       remove_directory ${CMAKE_CURRENT_BINARY_DIR}/html)
     add_dependencies(docs-lldb-html swig_wrapper_python
-                     lldb-python-doc-package clean-lldb-html)
+                     lldb-python-doc-package clean-lldb-html lldb-doc-autogen)
   endif()
 
   if (${SPHINX_OUTPUT_MAN})

lldb/docs/_ext/lldb_setting.py

@@ -0,0 +1,79 @@
+from docutils.parsers.rst import directives
+from docutils import nodes
+
+from sphinx import addnodes
+from sphinx.application import Sphinx
+from sphinx.directives import ObjectDescription
+from sphinx.util.docfields import Field, GroupedField
+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"
+#
+# The verbosity level used by dwim-print.
+#
+# :enum none: Use no verbosity when running dwim-print.
+# :enum expression: Use partial verbosity when running dwim-print - display a message when `expression` evaluation is used.
+# :enum full: Use full verbosity when running dwim-print.
+# :default: none
+# ```
+class LLDBSetting(ObjectDescription):
+    option_spec = {
+        "type": directives.unchanged,
+    }
+    doc_field_types = [
+        LiteralField(
+            "default",
+            label="Default",
+            has_arg=False,
+            names=("default",),
+        ),
+        GroupedField("enum", label="Enumerations", names=("enum",)),
+        LiteralField(
+            "minimum", label="Minimum", has_arg=False, names=("min", "minimum")
+        ),
+        LiteralField(
+            "maximum", label="Maximum", has_arg=False, names=("max", "maximum")
+        ),
+    ]
+
+    def handle_signature(self, sig: str, signode: addnodes.desc_signature):
+        typ = self.options.get("type", None)
+
+        desc = addnodes.desc_name(text=sig)
+        desc += nodes.inline(
+            "",
+            typ,
+            classes=[
+                "lldb-setting-type",
+                f"lldb-setting-type-{llvm_slug.make_slug(typ)}",
+            ],
+        )
+        signode["ids"].append(sig)
+        signode += desc
+
+
+def setup(app: Sphinx):
+    app.add_directive("lldbsetting", LLDBSetting)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

lldb/docs/_static/lldb-setting.css

@@ -0,0 +1,82 @@
+/* 
+  Terms use normal weight and upper case by default.
+  For settings, the term should be bold and use the original case.
+*/
+dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(
+    .simple
+  ).lldbsetting
+  .field-list
+  > dt {
+  text-transform: none;
+  font-weight: bold;
+}
+
+.lldb-setting-type {
+  --setting-color: var(--light-color);
+  --background-opacity: 0.1;
+}
+
+.lldb-setting-type {
+  float: right;
+  text-align: right;
+  text-indent: 0;
+  line-height: 1.4;
+  background-color: rgba(var(--setting-color), var(--background-opacity));
+  padding: 0px 8px;
+  border-radius: 99999px;
+  border: rgba(var(--setting-color), 1) 1px solid;
+  font-size: 0.9em;
+  color: rgba(var(--setting-color), 1);
+}
+
+body[data-theme="dark"] .lldb-setting-type {
+  --setting-color: var(--dark-color);
+  --background-opacity: 0.2;
+}
+@media (prefers-color-scheme: dark) {
+  body[data-theme="auto"] .lldb-setting-type {
+    --setting-color: var(--dark-color);
+    --background-opacity: 0.2;
+  }
+}
+
+/* anything string-like (default) */
+.lldb-setting-type-string,
+.lldb-setting-type /* fallback */ {
+  --dark-color: 255, 177, 38;
+  --light-color: 125, 98, 1;
+}
+
+/* array-like */
+.lldb-setting-type-arguments,
+.lldb-setting-type-array,
+.lldb-setting-type-file-list {
+  --dark-color: 211, 131, 255;
+  --light-color: 64, 33, 242;
+}
+
+/* map-like */
+.lldb-setting-type-dictionary,
+.lldb-setting-type-path-map {
+  --dark-color: 243, 0, 255;
+  --light-color: 157, 0, 183;
+}
+
+/* boolean */
+.lldb-setting-type-boolean {
+  --dark-color: 29, 180, 8;
+  --light-color: 0, 123, 33;
+}
+
+/* numbers */
+.lldb-setting-type-int,
+.lldb-setting-type-unsigned {
+  --dark-color: 80, 164, 198;
+  --light-color: 1, 108, 140;
+}
+
+/* enum */
+.lldb-setting-type-enum {
+  --dark-color: 255, 87, 73;
+  --light-color: 191, 3, 10;
+}

lldb/docs/conf.py

@@ -12,6 +12,7 @@
 # serve to show the default.
 import sys, os, re, shutil
 from datetime import date
+from pathlib import Path
 
 # Add path for llvm_slug module.
 sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "llvm", "docs")))
@@ -41,9 +42,16 @@
 # If your documentation needs a minimal Sphinx version, state it here.
 # needs_sphinx = '1.0'
 
+sys.path.append(str(Path("_ext").resolve()))
+
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.todo", "sphinx.ext.mathjax", "sphinx.ext.intersphinx"]
+extensions = [
+    "sphinx.ext.todo",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.intersphinx",
+    "lldb_setting",
+]
 
 # When building man pages, we do not use the markdown pages,
 # So, we can continue without the myst_parser dependencies.
@@ -59,6 +67,7 @@
 # Automatic anchors for markdown titles
 myst_heading_anchors = 6
 myst_heading_slug_func = "llvm_slug.make_slug"
+myst_enable_extensions = ["fieldlist"]
 
 autodoc_default_options = {"special-members": True}
 
@@ -132,7 +141,7 @@
 # included by any doctree (as the manpage ignores those pages but they are
 # potentially still around from a previous website generation).
 if building_man_page:
-    exclude_patterns.append(automodapi_toctreedirnm)
+    exclude_patterns += [automodapi_toctreedirnm, "use/settings.md"]
 # Use the recommended 'any' rule so that referencing SB API classes is possible
 # by just writing `SBData`.
 default_role = "any"
@@ -192,7 +201,10 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ["_static"]
+html_static_path = ["_static"]
+html_css_files = [
+    "lldb-setting.css",
+]
 
 html_extra_path = [".htaccess"]
 

lldb/docs/index.rst

@@ -137,6 +137,7 @@ interesting areas to contribute to lldb.
    use/aarch64-linux
    use/symbolfilejson
    use/mcp
+   use/settings
    use/troubleshooting
    use/links
    Man Page <man/lldb>

lldb/docs/use/.gitignore

@@ -0,0 +1,2 @@
+# autogenerated
+/settings.md

lldb/include/lldb/Interpreter/OptionValueEnumeration.h

@@ -70,6 +70,8 @@ class OptionValueEnumeration
 
   void SetDefaultValue(enum_type value) { m_default_value = value; }
 
+  const EnumerationMap &Enumerations() const { return m_enumerations; }
+
 protected:
   void SetEnumerations(const OptionEnumValues &enumerators);
   void DumpEnum(Stream &strm, enum_type value);

lldb/include/lldb/Interpreter/OptionValueFormatEntity.h

@@ -45,6 +45,9 @@ class OptionValueFormatEntity
 
   const FormatEntity::Entry &GetDefaultValue() const { return m_default_entry; }
 
+  llvm::StringRef GetDefaultFormatStr() const { return m_default_format; }
+  std::string GetEscapedDefaultFormatStr() const;
+
 protected:
   std::string m_current_format;
   std::string m_default_format;

lldb/include/lldb/Interpreter/OptionValueProperties.h

@@ -82,6 +82,11 @@ class OptionValueProperties
     return ProtectedGetPropertyAtIndex(idx);
   }
 
+  virtual size_t
+  GetNumProperties(const ExecutionContext *exe_ctx = nullptr) const {
+    return m_properties.size();
+  }
+
   // Property can be a property path like
   // "target.process.extra-startup-command"
   virtual const Property *

lldb/include/lldb/Interpreter/OptionValueRegex.h

@@ -55,6 +55,8 @@ class OptionValueRegex : public Cloneable<OptionValueRegex, OptionValue> {
 
   bool IsValid() const { return m_regex.IsValid(); }
 
+  llvm::StringRef GetDefaultValue() const { return m_default_regex_str; }
+
 protected:
   RegularExpression m_regex;
   std::string m_default_regex_str;