[mlir] Enable generation of type constraint docs

[marbre]

Summary

This enables generating the documentation of type constraints. So far
this documentation is only generated as part of the full docs, generated
via --gen-dialect-doc.

[jpienaar]

OOC when would one want to just have the type constraints? I was thinking most were moving towards full doc generation

[marbre]

In D106541#2896241, @jpienaar wrote:

OOC when would one want to just have the type constraints? I was thinking most were moving towards full doc generation

Well I plan to extend the EmitC dialect documentation. In order to do so, I need to replace

add_mlir_doc(EmitC EmitC Dialects/ -gen-dialect-doc)

I think the Buildin dialect is a good reference here:

add_mlir_doc(BuiltinAttributes BuiltinAttributes Dialects/ -gen-attrdef-doc)
add_mlir_doc(BuiltinLocationAttributes BuiltinLocationAttributes Dialects/ -gen-attrdef-doc)
add_mlir_doc(BuiltinOps BuiltinOps Dialects/ -gen-op-doc)
add_mlir_doc(BuiltinTypes BuiltinTypes Dialects/ -gen-typedef-doc)
add_mlir_doc(BuiltinTypes BuiltinTypeInterfaces Dialects/ -gen-type-interface-docs)

This allows to place the TOC at the correct position, to have a header like # 'emitc' Dialect only once, etc. This is hard to achieve when relying on -gen-dialect-doc, e.g. you cannot have the TOC at the top of the documentation or you have multiple TOCs. However, with not using -gen-dialect-doc, you loose the ability to document the type constraints.

[rriddle]

In D106541#2896255, @marbre wrote:

In D106541#2896241, @jpienaar wrote:

OOC when would one want to just have the type constraints? I was thinking most were moving towards full doc generation

Well I plan to extend the EmitC dialect documentation. In order to do so, I need to replace

add_mlir_doc(EmitC EmitC Dialects/ -gen-dialect-doc)

I think the Buildin dialect is a good reference here:

add_mlir_doc(BuiltinAttributes BuiltinAttributes Dialects/ -gen-attrdef-doc)
add_mlir_doc(BuiltinLocationAttributes BuiltinLocationAttributes Dialects/ -gen-attrdef-doc)
add_mlir_doc(BuiltinOps BuiltinOps Dialects/ -gen-op-doc)
add_mlir_doc(BuiltinTypes BuiltinTypes Dialects/ -gen-typedef-doc)
add_mlir_doc(BuiltinTypes BuiltinTypeInterfaces Dialects/ -gen-type-interface-docs)

This allows to place the TOC at the correct position, to have a header like # 'emitc' Dialect only once, etc. This is hard to achieve when relying on -gen-dialect-doc, e.g. you cannot have the TOC at the top of the documentation or you have multiple TOCs. However, with not using -gen-dialect-doc, you loose the ability to document the type constraints.

Have you looked into fixing the issues with gen-dialect-doc? Or is it not easily feasible?

[marbre]

In D106541#2897051, @rriddle wrote:

Have you looked into fixing the issues with gen-dialect-doc? Or is it not easily feasible?

I don't know if there is anything to fix in gen-dialect-doc. From my point of view it's fine that every generated file starts with

 # '${dialect} Dialect'

[TOC]

Otherwise you cannot fully rely on a pure auto-generated documentation. Removing those two auto-generated lines would force to add a custom markdown file to every dialect, which seems unnecessary. So I am not sure how we could "fix" gen-dialect-doc, but I am open for suggestions.
Anyway, if you want to put something in between of those two lines, you could do this generating several docs + adding a custom markdown file as the Builtin dialect does and that's fine. However, so far no possibility to generate docs on type constraints.

mlir/tools/mlir-tblgen/OpDocGen.cpp

 //===----------------------------------------------------------------------===//
 
 static void emitTypeDoc(const Type &type, raw_ostream &os) {
   os << "### " << type.getSummary() << "\n";
   emitDescription(type.getDescription(), os);
   os << "\n";
 }
 
+static void emitTypeDoc(const RecordKeeper &recordKeeper, raw_ostream &os) {
+  std::vector<Record *> typeDefs =
+      recordKeeper.getAllDerivedDefinitions("DialectType");
+
+  os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n";
+  os << "## Type constraint definition\n\n";
+  for (auto *typeDef : typeDefs)
+    emitTypeDoc(Type(typeDef), os);
+}
+
 //===----------------------------------------------------------------------===//
 // TypeDef Documentation
 //===----------------------------------------------------------------------===//
 
 static void emitAttrOrTypeDefAssemblyFormat(const AttrOrTypeDef &def,
                                             raw_ostream &os) {
   SmallVector<AttrOrTypeParameter, 4> parameters;
   def.getParameters(parameters);

 static mlir::GenRegistration
     genTypeRegister("gen-typedef-doc", "Generate dialect type documentation",
                     [](const RecordKeeper &records, raw_ostream &os) {
                       emitAttrOrTypeDefDoc(records, os, "TypeDef");
                       return false;
                     });
 
 static mlir::GenRegistration
+    genTypeConstraintRegister("gen-type-constraint-doc",
+                              "Generate dialect type constraint documentation",
+                              [](const RecordKeeper &records, raw_ostream &os) {
+                                emitTypeDoc(records, os);
+                                return false;
+                              });
+
+static mlir::GenRegistration
     genRegister("gen-dialect-doc", "Generate dialect documentation",
                 [](const RecordKeeper &records, raw_ostream &os) {
                   emitDialectDoc(records, os);
                   return false;
                 });