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

[Benjamin Maxwell]

https://github.com/MacDue created https://github.com/llvm/llvm-project/pull/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)


>From 947df96e1646645d75e74c3b9ba837ebbeb86fab Mon Sep 17 00:00:00 2001
From: Benjamin Maxwell <benjamin.maxwell at arm.com>
Date: Thu, 21 Sep 2023 11:57:37 +0000
Subject: [PATCH] [mlir][docgen] Display full attribute descriptions in
 expandable regions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 mlir/include/mlir/IR/EnumAttr.td    |  8 +++++++
 mlir/tools/mlir-tblgen/OpDocGen.cpp | 36 +++++++++++++++++++++++++----
 2 files changed, 40 insertions(+), 4 deletions(-)

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..d2538fc49b20d0d 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;
@@ -195,13 +202,34 @@ static void emitOpDoc(const Operator &op, raw_ostream &os) {
     // 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.