[MLIR][OpenMP][Docs] NFC: Reorganize 'omp' dialect documentation #107232
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
skatrak
requested review from
ftynse,
Meinersbur,
jsjodin,
tblah,
kiranchandramohan,
mjklemm,
DominikAdamski,
dpalermo,
kiranktp and
kparzysz
|
@llvm/pr-subscribers-mlir-openmp @llvm/pr-subscribers-mlir Author: Sergio Afonso (skatrak) ChangesThis 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.
Full diff: https://github.com/llvm/llvm-project/pull/107232.diff 2 Files Affected:
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]
|
This was referenced Sep 4, 2024
mjklemm
approved these changes
Sep 4, 2024
|
Can anyone familiar with the structure of MLIR docs pages take a quick look and let me know if this reorganization is fine? I've been able to build the mlir-www documentation webpage incorporating this change locally and it looks as intended. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
accdialect currently does, but it results in the addition of two equal TOCs. It would be possible to move theincludebefore 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.linalgdialect. 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 forDialectAttr,DialectTypeandEnumAttrInfodefinitions or making the TOC optional through a command line option.