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

[Scott Todd]

================
@@ -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>";
----------------
ScottTodd wrote:

I'll echo the comment on the merged commit (https://github.com/llvm/llvm-project/commit/d339d8fede356f0acfad6d6c1bb960269f2467a9#commitcomment-128747641):
> Hi folks. This breaks documentation generators for out-of-tree projects that don't have the custom markdown shortcode. Is there any way we could make this opt-in instead of breaking?
> 
> I can add the custom shortcode on our project downstream easily enough, but I'm just hoping upstream folks can consider us out-of-tree folks when making changes that don't really need to be backwards incompatible.

This breaks downstream projects that use other markdown renderers. Please revert and/or make this opt-in via a flag like https://github.com/llvm/llvm-project/blob/9ce8103e87397578137daf893bfc410b3a7db1dc/mlir/tools/mlir-tblgen/OpDocGen.cpp#L36-L44

Here is how one renderer handles this custom syntax (i.e. unsupported, broken): 
![image](https://github.com/llvm/llvm-project/assets/4010439/94b691e0-a799-4d6f-8e51-dd3bd1e219e6)

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