[Mlir-commits] [mlir] [MLIR][OpenMP][Docs] NFC: Reorganize 'omp' dialect documentation (PR #107232)

[Sergio Afonso]

https://github.com/skatrak updated https://github.com/llvm/llvm-project/pull/107232

>From 9e199fbcc857fe0b93bdff7cde8d13365766dabf Mon Sep 17 00:00:00 2001
From: Sergio Afonso <safonsof at amd.com>
Date: Tue, 3 Sep 2024 10:33:15 +0100
Subject: [PATCH 1/2] [MLIR][OpenMP][Docs] NFC: Reorganize 'omp' dialect
 documentation

This patch creates a handwritten main documentation page for the OpenMP dialect
linking to the ODS-generated one as a sub-section.

This new page can be extended to better describe overall design decisions of
the dialect rather than relying exclusively on documentation generated
automatically from ODS descriptions. After some investigation, there seem to be
a few main ways we could structure dialect documentation to allow the
introduction of possibly extensive handwritten text.
  - Create a top-level OpenMPDialect.td file that includes the auto-generated
one. This is what the `acc` dialect currently does, but it results in the
addition of two equal TOCs (one of them automatically generated). It would be
possible to move the `include` before all handwritten sections so that the page
would have a single TOC, but I believe moving general descriptions to the end
of the document would hurt readability. Also keeping the section order without
introducing a second TOC would mean the TOC would be inserted somewhere halfway
through the page, which isn't useful.
  - Create an OpenMPDialect directory with an _index.md including the
auto-generated documentation. This is a different way of reproducing the same
issues described above, which is what is currently done for the `linalg`
dialect. The multiple TOC issue there is avoided by only including
automatically-generated documentation for operations (i.e. `mlir-tblgen
-gen-op-doc`) rather than for dialects (i.e. `mlir-tblgen -gen-dialect-doc`).
That approach would make it impossible to generate all of the documentation
without adding new tablegen backends for `DialectAttr`, `DialectType` and
`EnumAttrInfo` definitions or making the TOC optional through a command line
option.
  - Create an OpenMPDialect directory with an _index.md that does not include
the auto-generated documentation. Instead, link to another document in that
directory with includes it. This is the approach taken here, and it circumvents
all these issues without having to make any changes to tablegen backends.
---
 mlir/docs/Dialects/OpenMPDialect/ODS.md    |  3 +++
 mlir/docs/Dialects/OpenMPDialect/_index.md | 14 ++++++++++++++
 2 files changed, 17 insertions(+)
 create mode 100644 mlir/docs/Dialects/OpenMPDialect/ODS.md
 create mode 100644 mlir/docs/Dialects/OpenMPDialect/_index.md

diff --git a/mlir/docs/Dialects/OpenMPDialect/ODS.md b/mlir/docs/Dialects/OpenMPDialect/ODS.md
new file mode 100644
index 00000000000000..51c61c86ebc6e7
--- /dev/null
+++ b/mlir/docs/Dialects/OpenMPDialect/ODS.md
@@ -0,0 +1,3 @@
+# ODS Documentation
+
+[include "Dialects/OpenMPDialect.md"]
diff --git a/mlir/docs/Dialects/OpenMPDialect/_index.md b/mlir/docs/Dialects/OpenMPDialect/_index.md
new file mode 100644
index 00000000000000..f4a468ca84da99
--- /dev/null
+++ b/mlir/docs/Dialects/OpenMPDialect/_index.md
@@ -0,0 +1,14 @@
+# 'omp' Dialect
+
+The `omp` dialect is for representing directives, clauses and other definitions
+of the OpenMP programming model. This directive-based programming model, defined
+for the C, C++ and Fortran programming languages, provides abstractions to
+simplify the development of parallel and accelerated programs.
+
+Operations in this MLIR dialect generally correspond to a single OpenMP
+directive, taking arguments that represent their supported clauses, though this
+is not always the case. For a detailed information of operations, types and
+other definitions in this dialect, refer to the automatically-generated
+[ODS Documentation](ODS.md).
+
+[TOC]

>From a3142aa5901d0411fac9380e58987dcad41223a0 Mon Sep 17 00:00:00 2001
From: Sergio Afonso <safonsof at amd.com>
Date: Thu, 5 Sep 2024 11:21:13 +0100
Subject: [PATCH 2/2] Add links to the OpenMP ARB website

---
 mlir/docs/Dialects/OpenMPDialect/_index.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/mlir/docs/Dialects/OpenMPDialect/_index.md b/mlir/docs/Dialects/OpenMPDialect/_index.md
index f4a468ca84da99..6c9ef0abf290de 100644
--- a/mlir/docs/Dialects/OpenMPDialect/_index.md
+++ b/mlir/docs/Dialects/OpenMPDialect/_index.md
@@ -1,9 +1,11 @@
 # 'omp' Dialect
 
 The `omp` dialect is for representing directives, clauses and other definitions
-of the OpenMP programming model. This directive-based programming model, defined
-for the C, C++ and Fortran programming languages, provides abstractions to
-simplify the development of parallel and accelerated programs.
+of the [OpenMP programming model](https://www.openmp.org). This directive-based
+programming model, defined for the C, C++ and Fortran programming languages,
+provides abstractions to simplify the development of parallel and accelerated
+programs. All versions of the OpenMP specification can be found
+[here](https://www.openmp.org/specifications/).
 
 Operations in this MLIR dialect generally correspond to a single OpenMP
 directive, taking arguments that represent their supported clauses, though this