[mlir][linalg][python] Update integration of OpDSL doc (NFC).

Move the OpDSL doc to a linalg sub folder and updated the integration in the main linalg documentation.

Differential Revision: https://reviews.llvm.org/D105188

mlir/docs/Tools/LinalgOpDsl.md → mlir/docs/Dialects/Linalg/OpDSL.md

@@ -1,12 +1,12 @@
-# linalg_opdsl tool
+# Linalg OpDSL
 
 Python based DSL for authoring Linalg op definitions and generating
 `linalg.generic` IR based on them for samples.
 
-The tool `linalg_opdsl` provides a high level DSL for constructing structured op
-definitions in a way that can be exported to built-in, named structured ops via
-the above YAML-based definitions or used interactively to emit corresponding
-`linalg.generic` IR for the composition.
+The Linalg OpDSL is a high level DSL for constructing structured op definitions
+in a way that can be exported to built-in, named structured ops via
+[YAML-based definitions](_index.md/#yaml-gen) or used interactively to emit
+corresponding `linalg.generic` IR for the composition.
 
 ## Basic usage
 

mlir/docs/Dialects/Linalg.md → mlir/docs/Dialects/Linalg/_index.md

@@ -10,7 +10,7 @@ Linalg is designed to solve the High-level Hierarchical Optimization (HHO box)
 in MLIR and to interoperate nicely within a *Mixture Of Expert Compilers*
 environment (i.e. the *CGSel* box).
 
-The [Rationale Document](../Rationale/RationaleLinalgDialect.md) goes into
+The [Rationale Document](../../Rationale/RationaleLinalgDialect.md) goes into
 significantly more design and architectural decision details.
 
 ## Set of Key Transformations<a name="key_transformations"></a>
@@ -37,9 +37,9 @@ Linalg IR and that have influenced its design:
 ## High-Level Description of Linalg Ops<a name="linalg_ops"></a>
 
 Linalg takes at least some inspiration from all previously
-[listed prior art](../Rationale/RationaleLinalgDialect.md/#prior-art). The design enables the definition of
-***CustomOps*** with generic properties that enable
-[key transformations](#key_transformations), including lowering to scalar
+[listed prior art](../../Rationale/RationaleLinalgDialect.md/#prior-art). The
+design enables the definition of ***CustomOps*** with generic properties that
+enable [key transformations](#key_transformations), including lowering to scalar
 load/store and other operations or to external library calls and intrinsics.
 
 These ops can have ***either tensor or buffer*** as both input and output
@@ -70,7 +70,7 @@ abstraction on tensors and buffers. This `linalg.generic` operation can express
 custom operations that optionally have *indexing semantics* (by accessing the
 iteration indices using the `linalg.index` operation). The properties of
 `linalg.generic` are the result of applying the guiding principles described in
-the [Rationale Document](../Rationale/RationaleLinalgDialect.md). They are
+the [Rationale Document](../../Rationale/RationaleLinalgDialect.md). They are
 listed next, with a brief example and discussion for each.
 
 #### Property 1: Input and Output Operands Define The Iteration Space<a name="prop1"></a>
@@ -492,7 +492,7 @@ As it stands, the six properties above define the semantics of a
 `linalg.generic` op. It is an open question whether all of these semantics are
 strictly necessary in practice and whether some should or could be derived
 automatically while still maintaining the
-[core guiding principles](../Rationale/RationaleLinalgDialect.md/#core-guiding-principlesa-nameguiding_principlesa).
+[core guiding principles](../../Rationale/RationaleLinalgDialect.md/#core-guiding-principlesa-nameguiding_principlesa).
 
 For the time being, we have settled on the combination of these properties
 because of empirical evidence building and working on multiple high-level
@@ -662,13 +662,16 @@ void batchmatmul::regionBuilder(ArrayRef<BlockArgument> args) {
 }
 ```
 
-### YAML Based Named Structured Ops
+### YAML Based Named Structured Ops<a name="yaml-gen"></a>
 
 Linalg provides a declarative generation tool (`mlir-linalg-ods-yaml-gen`) to
 automatically produce named ops from a YAML-based op description format intended
-to capture the structure of the named ops and be generated from a higher level
-"mathy" DSL syntax. This facility is currently in flight and is intended to
-subsume the above when ready. See the C++ class to YAML mapping traits in
+to capture the structure of the named ops. The YAML-based op descriptions are
+generated from a higher level [DSL](OpDSL.md) and are not meant to be edited
+directly.
+
+This facility is currently in flight and is intended to subsume the above when
+ready. See the C++ class to YAML mapping traits in
 `mlir-mlinalg-ods-yaml-gen.cpp` as the source of truth for the schema.
 
 Most of the above documentation roughly applies to this path and will be ported

mlir/docs/Rationale/RationaleLinalgDialect.md

@@ -102,9 +102,9 @@ to the *structured control flow* dialect (named `LoopOps`).
 More components can be extracted, redesigned and generalized when new uses or
 requirements arise.
 
-Several [design questions](../Dialects/Linalg.md/#open_issues) remain open in Linalg, which does not
-claim to be a general solution to all compilation problems.
-It does aim at driving thinking and implementations of domain-specific
+Several [design questions](../Dialects/Linalg/_index.md/#open_issues) remain
+open in Linalg, which does not claim to be a general solution to all compilation
+problems. It does aim at driving thinking and implementations of domain-specific
 abstractions where programmer's intent can be captured at a very high level,
 directly in the IR.
 
@@ -566,18 +566,18 @@ reconcile [core guiding principles](#guiding_principles) with real-world
 requirements when producing an implementation based on MLIR.
 
 ### Algorithms + Data Structures = Programs<a name="data_and_compute"></a>
+
 This is a twist on Niklaus Wirth's formulation but captures the essence of the
 design of Linalg: control-flow does not exist in a vacuum, independently of
-data.
-On the contrary, there is a very strong relationship between control-flow and
-data structures: one cannot exist without the other. This has multiple
-implications on the [semantics of Linalg Ops](../Dialects/Linalg.md/#linalg_op) and their
-transformations. In particular, this observation influences whether
-certain transformations are better done:
-- as control flow or data structure manipulation,
-- on Linalg ops attributes or on loops after some partial lowering
-occurred,
-- as extensions to the Linalg dialect in terms of new ops or attributes.
+data. On the contrary, there is a very strong relationship between control-flow
+and data structures: one cannot exist without the other. This has multiple
+implications on the
+[semantics of Linalg Ops](../Dialects/Linalg/_index.md/#linalg_ops) and their
+transformations. In particular, this observation influences whether certain
+transformations are better done: - as control flow or data structure
+manipulation, - on Linalg ops attributes or on loops after some partial lowering
+occurred, - as extensions to the Linalg dialect in terms of new ops or
+attributes.
 
 ### The Dialect Need not be Closed Under Transformations<a name="dialect_not_closed"></a>
 This is probably the most surprising and counter-intuitive
@@ -615,9 +615,8 @@ Principles](#guiding_principles)---with the following picture.
 <img width="1200" alt="MLIR Codegen Flow"
 src="https://user-images.githubusercontent.com/10148468/73613904-2f720a00-45c8-11ea-8265-1c856c02525b.png">
 
-This figure is not meant to be perfectly accurate but a rough map of
-how we view the distribution of structural information in existing
-systems, from a codegen-friendly angle. Unsurprisingly, the
-[Linalg Dialect](../Dialects/Linalg.md) and its
-future evolutions aspire to a position in the top-right of this map.
-
+This figure is not meant to be perfectly accurate but a rough map of how we view
+the distribution of structural information in existing systems, from a
+codegen-friendly angle. Unsurprisingly, the
+[Linalg Dialect](../Dialects/Linalg/_index.md) and its future evolutions aspire
+to a position in the top-right of this map.