[Mlir-commits] [mlir] d339d8f - [mlir][docgen] Display full attribute descriptions in expandable regions (#67009)

[llvmlistbot at llvm.org]

Author: Benjamin Maxwell
Date: 2023-09-27T12:22:24+01:00
New Revision: d339d8fede356f0acfad6d6c1bb960269f2467a9

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

LOG: [mlir][docgen] Display full attribute descriptions in expandable regions (#67009)

This updates the table of op attributes so that clicking the summary
expands to show the complete description.

```
   Attribute | MLIR Type | Description
   <name>      <type>      ▶ <summary>  <-- Click to expand
```

Enum attributes have now also been updated to generate a description
that lists all the cases (with both their MLIR and C++ names). This
makes viewing enums on the MLIR docs much nicer.

**Example**

Default view:

![image](https://github.com/llvm/llvm-project/assets/11597044/922669c7-b838-4230-bcfd-a77cde0f335d)

Expanded:

![image](https://github.com/llvm/llvm-project/assets/11597044/41da086e-a5ce-45dd-9f44-9d10a4d5f2e1)

---

This requires: https://github.com/llvm/mlir-www/pull/158 (adds a very
simple markdown shortcode)

Added: 
    

Modified: 
    mlir/include/mlir/IR/EnumAttr.td
    mlir/tools/mlir-tblgen/OpDocGen.cpp

Removed: 
    


################################################################################
diff  --git a/mlir/include/mlir/IR/EnumAttr.td b/mlir/include/mlir/IR/EnumAttr.td
index 485c5266f3cfdfa..cb918b5eceb1a19 100644
--- a/mlir/include/mlir/IR/EnumAttr.td
+++ b/mlir/include/mlir/IR/EnumAttr.td
@@ -113,6 +113,13 @@ class I64BitEnumAttrCaseGroup<string sym, list<BitEnumAttrCaseBase> cases,
 class EnumAttrInfo<
     string name, list<EnumAttrCaseInfo> cases, Attr baseClass> :
       Attr<baseClass.predicate, baseClass.summary> {
+
+  // Generate a description of this enums members for the MLIR docs.
+  let description =
+        "Enum cases:\n" # !interleave(
+          !foreach(case, cases,
+              "* " # case.str  # " (`" # case.symbol # "`)"), "\n");
+
   // The C++ enum class name
   string className = name;
 
@@ -381,6 +388,7 @@ class EnumAttr<Dialect dialect, EnumAttrInfo enumInfo, string name = "",
                list <Trait> traits = []>
     : AttrDef<dialect, enumInfo.className, traits> {
   let summary = enumInfo.summary;
+  let description = enumInfo.description;
 
   // The backing enumeration.
   EnumAttrInfo enum = enumInfo;

diff  --git a/mlir/tools/mlir-tblgen/OpDocGen.cpp b/mlir/tools/mlir-tblgen/OpDocGen.cpp
index c546763880a853f..088d34597f315fc 100644
--- a/mlir/tools/mlir-tblgen/OpDocGen.cpp
+++ b/mlir/tools/mlir-tblgen/OpDocGen.cpp
@@ -173,6 +173,13 @@ static void emitOpTraitsDoc(const Operator &op, raw_ostream &os) {
   }
 }
 
+static StringRef resolveAttrDescription(const Attribute &attr) {
+  StringRef description = attr.getDescription();
+  if (description.empty())
+    return attr.getBaseAttr().getDescription();
+  return description;
+}
+
 static void emitOpDoc(const Operator &op, raw_ostream &os) {
   std::string classNameStr = op.getQualCppClassName();
   StringRef className = classNameStr;
@@ -192,16 +199,35 @@ static void emitOpDoc(const Operator &op, raw_ostream &os) {
 
   // Emit attributes.
   if (op.getNumAttributes() != 0) {
-    // TODO: Attributes are only documented by TableGen name, with no further
-    // info. This should be improved.
     os << "\n#### Attributes:\n\n";
-    os << "| Attribute | MLIR Type | Description |\n"
-       << "| :-------: | :-------: | ----------- |\n";
+    // Note: This table is HTML rather than markdown so the attribute's
+    // description can appear in an expandable region. The description may be
+    // multiple lines, which is not supported in a markdown table cell.
+    os << "<table>\n";
+    // Header.
+    os << "<tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr>\n";
     for (const auto &it : op.getAttributes()) {
       StringRef storageType = it.attr.getStorageType();
-      os << "| `" << it.name << "` | " << storageType << " | "
-         << it.attr.getSummary() << "\n";
+      // Name and storage type.
+      os << "<tr>";
+      os << "<td><code>" << it.name << "</code></td><td>" << storageType
+         << "</td><td>";
+      StringRef description = resolveAttrDescription(it.attr);
+      if (!description.empty()) {
+        // Expandable description.
+        // This appears as just the summary, but when clicked shows the full
+        // description.
+        os << "<details>"
+           << "<summary>" << it.attr.getSummary() << "</summary>"
+           << "{{% markdown %}}" << description << "{{% /markdown %}}"
+           << "</details>";
+      } else {
+        // Fallback: Single-line summary.
+        os << it.attr.getSummary();
+      }
+      os << "</td></tr>\n";
     }
+    os << "<table>\n";
   }
 
   // Emit each of the operands.