Skip to content

Commit e9869b5

Browse files
authored
[mlir][docgen] Add ops source link (#73657)
This patch suggests to change two things. Firstly, it adds a source link above the generated operations docs (above the `emitOpDoc` calls). This link will point directly to the source TableGen file for the group of operations. For example, for the current [`amdgpu`](https://mlir.llvm.org/docs/Dialects/AMDGPU/) page, the link will add a source link below the "Operation definition" heading pointing to [`mlir/include/mlir/Dialect/AMDGPU/IR/AMDGPU.td`](https://github.com/llvm/llvm-project/blob/main/mlir/include/mlir/Dialect/AMDGPU/IR/AMDGPU.td). The link is wrapped in a "op-definitions-source-link" class which could allow for custom styling, but it also looks reasonable without custom styling I think: ![afbeelding](https://github.com/llvm/llvm-project/assets/20724914/7c0e59b9-b14b-4f5d-a671-c87e857a7b03) Secondly, this patch simplifies the header names such as "Operation definition" and "Attribute definition" to "Operations" and "Attributes" respectively. This is in line with manually defined subheadings on pages such as the one for the [`vector`](https://mlir.llvm.org/docs/Dialects/Vector/#operations) dialect.
1 parent b724561 commit e9869b5

File tree

2 files changed

+26
-12
lines changed

2 files changed

+26
-12
lines changed

mlir/test/mlir-tblgen/gen-dialect-doc.td

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ def TestTypeDefParams : TypeDef<Test_Dialect, "TestTypeDefParams"> {
8585
// CHECK: Interfaces: NoMemoryEffect (MemoryEffectOpInterface)
8686
// CHECK: Effects: MemoryEffects::Effect{}
8787

88-
// CHECK: ## Attribute constraint definition
88+
// CHECK: ## Attribute constraints
8989
// CHECK: ### attribute summary
9090
// CHECK: attribute description
9191

@@ -97,7 +97,7 @@ def TestTypeDefParams : TypeDef<Test_Dialect, "TestTypeDefParams"> {
9797
// CHECK: Syntax:
9898
// CHECK: #test.test_attr_def_params
9999

100-
// CHECK: ## Type constraint definition
100+
// CHECK: ## Type constraints
101101
// CHECK: ### type summary
102102
// CHECK: type description
103103

mlir/tools/mlir-tblgen/OpDocGen.cpp

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -265,10 +265,22 @@ static void emitOpDoc(const Operator &op, raw_ostream &os) {
265265
os << "\n";
266266
}
267267

268+
static void emitSourceLink(StringRef inputFilename, raw_ostream &os) {
269+
size_t pathBegin = inputFilename.find("mlir/include/mlir/");
270+
if (pathBegin == StringRef::npos)
271+
return;
272+
273+
StringRef inputFromMlirInclude = inputFilename.substr(pathBegin);
274+
275+
os << "[source](https://github.com/llvm/llvm-project/blob/main/"
276+
<< inputFromMlirInclude << ")\n\n";
277+
}
278+
268279
static void emitOpDoc(const RecordKeeper &recordKeeper, raw_ostream &os) {
269280
auto opDefs = getRequestedOpDefinitions(recordKeeper);
270281

271282
os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n";
283+
emitSourceLink(recordKeeper.getInputFilename(), os);
272284
for (const llvm::Record *opDef : opDefs)
273285
emitOpDoc(Operator(opDef), os);
274286
}
@@ -392,12 +404,13 @@ static void maybeNest(bool nest, llvm::function_ref<void(raw_ostream &os)> fn,
392404
}
393405
}
394406

395-
static void emitBlock(ArrayRef<Attribute> attributes,
407+
static void emitBlock(ArrayRef<Attribute> attributes, StringRef inputFilename,
396408
ArrayRef<AttrDef> attrDefs, ArrayRef<OpDocGroup> ops,
397409
ArrayRef<Type> types, ArrayRef<TypeDef> typeDefs,
398410
raw_ostream &os) {
399411
if (!ops.empty()) {
400-
os << "## Operation definition\n\n";
412+
os << "## Operations\n\n";
413+
emitSourceLink(inputFilename, os);
401414
for (const OpDocGroup &grouping : ops) {
402415
bool nested = !grouping.summary.empty();
403416
maybeNest(
@@ -417,32 +430,32 @@ static void emitBlock(ArrayRef<Attribute> attributes,
417430
}
418431

419432
if (!attributes.empty()) {
420-
os << "## Attribute constraint definition\n\n";
433+
os << "## Attribute constraints\n\n";
421434
for (const Attribute &attr : attributes)
422435
emitAttrDoc(attr, os);
423436
}
424437

425438
if (!attrDefs.empty()) {
426-
os << "## Attribute definition\n\n";
439+
os << "## Attributes\n\n";
427440
for (const AttrDef &def : attrDefs)
428441
emitAttrOrTypeDefDoc(def, os);
429442
}
430443

431444
// TODO: Add link between use and def for types
432445
if (!types.empty()) {
433-
os << "## Type constraint definition\n\n";
446+
os << "## Type constraints\n\n";
434447
for (const Type &type : types)
435448
emitTypeDoc(type, os);
436449
}
437450

438451
if (!typeDefs.empty()) {
439-
os << "## Type definition\n\n";
452+
os << "## Types\n\n";
440453
for (const TypeDef &def : typeDefs)
441454
emitAttrOrTypeDefDoc(def, os);
442455
}
443456
}
444457

445-
static void emitDialectDoc(const Dialect &dialect,
458+
static void emitDialectDoc(const Dialect &dialect, StringRef inputFilename,
446459
ArrayRef<Attribute> attributes,
447460
ArrayRef<AttrDef> attrDefs, ArrayRef<OpDocGroup> ops,
448461
ArrayRef<Type> types, ArrayRef<TypeDef> typeDefs,
@@ -456,7 +469,7 @@ static void emitDialectDoc(const Dialect &dialect,
456469
if (!r.match(dialect.getDescription()))
457470
os << "[TOC]\n\n";
458471

459-
emitBlock(attributes, attrDefs, ops, types, typeDefs, os);
472+
emitBlock(attributes, inputFilename, attrDefs, ops, types, typeDefs, os);
460473
}
461474

462475
static bool emitDialectDoc(const RecordKeeper &recordKeeper, raw_ostream &os) {
@@ -536,8 +549,9 @@ static bool emitDialectDoc(const RecordKeeper &recordKeeper, raw_ostream &os) {
536549
});
537550

538551
os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n";
539-
emitDialectDoc(*dialect, dialectAttrs, dialectAttrDefs, dialectOps,
540-
dialectTypes, dialectTypeDefs, os);
552+
emitDialectDoc(*dialect, recordKeeper.getInputFilename(), dialectAttrs,
553+
dialectAttrDefs, dialectOps, dialectTypes, dialectTypeDefs,
554+
os);
541555
return false;
542556
}
543557

0 commit comments

Comments
 (0)