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

[llvmlistbot at llvm.org]

Author: Sergio Afonso
Date: 2024-09-16T11:22:03+01:00
New Revision: 0f86cb315429b3fe084a7205d40599a0d07e4882

URL: https://github.com/llvm/llvm-project/commit/0f86cb315429b3fe084a7205d40599a0d07e4882
DIFF: https://github.com/llvm/llvm-project/commit/0f86cb315429b3fe084a7205d40599a0d07e4882.diff

LOG: [MLIR][OpenMP][Docs] Reorganize 'omp' dialect documentation (NFC) (#107232)

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. 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 that includes it. This is the approach taken
here, and it circumvents all these issues without having to make any
changes to tablegen backends.

Added: 
    mlir/docs/Dialects/OpenMPDialect/ODS.md
    mlir/docs/Dialects/OpenMPDialect/_index.md

Modified: 
    

Removed: 
    


################################################################################
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..6c9ef0abf290de
--- /dev/null
+++ b/mlir/docs/Dialects/OpenMPDialect/_index.md
@@ -0,0 +1,16 @@
+# 'omp' Dialect
+
+The `omp` dialect is for representing directives, clauses and other definitions
+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
+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]