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

[gysit]

Summary

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

[stellaraccident]

Thanks - we should extend this doc with more detail at some point.

Regarding location, I spoke imprecisely: I think this needs to go under a new docs/Dialects/Linalg/OpDSL.md path. The existing docs/Dialects/Linalg.md should become an _index.md in that new parent dir.

Feel free to land such docs fixes directly (without review).

[gysit]

Move OpDSL and Linalg doc.

mlir/docs/Dialects/Linalg/OpDSL.md

-# 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
 
 The tool is bundled with the MLIR Python bindings. To use from the CMake build
 tree, MLIR must be build with Python bindings enabled
 (`-DMLIR_ENALBE_BINDINGS_PYTHON=ON`). Then add the `python` directory in the
 build tree to your `PYTHONPATH` environment variable (i.e. `export
 PYTHONPATH=$PWD/build/python`). Optionally, use an installed MLIR package, if

mlir/docs/Dialects/Linalg/_index.md

 # 'linalg' Dialect
 
 [TOC]
 
 ## Rationale
 
 <img width="90" align="left" alt="MLIR Codegen Flow" src="https://user-images.githubusercontent.com/10148468/73613629-c5586580-45c5-11ea-94b7-074aeea94c7b.png">
 
 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>
 
 The following key transformations have been central to driving the design of
 Linalg. They are all implemented in terms of the properties of the
 `linalg.generic` OpInterface and avoid the pitfall of relying on hardcoded
 one-off op knowledge.

 1.  Vectorization: Rewrite in Vector Form.
 1.  Lower to Loops (Affine, Generic, and Parallel).
 1.  Lower to Library Calls or Special Instructions, Intrinsics or ISA.
 1.  Partially Lower to Iterations Over a Finer-Grained Linalg Op.
 
 ## 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
 operands. Output tensors operands serve the purpose of providing a unifying
 abstraction and give a shape to the results. Output tensors can come in 2
 flavors and are always associated with a corresponding op result:
 
 1.  an "init tensor" output value which provides an initial value for a tensor

 ### Payload-Carrying Ops<a name="payload_ops"></a>
 
 Linalg defines a payload carrying operation that implements the
 [structured op](https://docs.google.com/presentation/d/1P-j1GrH6Q5gLBjao0afQ-GfvcAeF-QU4GXXeSy0eJ9I/edit#slide=id.p)
 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>
 
 A `linalg.generic` op fully *derives* the specification of its iteration space
 from its operands. The property enforces that a localized IR element (the op)
 *has* all the information needed to synthesize the control-flow required to
 iterate over its operands, according to their type. This notion of IR

 In the grander scheme, the reliance on late LICM was deemed a necessary risk.
 
 #### Putting it Together<a name="summary"></a>
 
 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
 compilers. As we lay those down and engage more with the community, we expect
 multiple rounds of discussions and design changes to the original architecture.
 
 ### Data Representation: Views<a name="views"></a>
 
void batchmatmul::regionBuilder(ArrayRef<BlockArgument> args) {
   using namespace intrinsics;
   Value _0(args[0]), _1(args[1]), _2(args[2]);
   Value _4 = std_mulf(_0, _1);
   Value _5 = std_addf(_2, _4);
   (linalg_yield(ValueRange{ _5 }));
 }
 ```
 
-### 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
 as migration continues.
 
 ## Open Issues and Design Alternatives<a name="open_issues"></a>
 
 Multiple open issues and design alternatives are in flight and it is time to lay

mlir/docs/Rationale/RationaleLinalgDialect.md

 preserving structure to allow calling into external C++ libraries with
 unsurprising ABI conventions;
 - the `linalg.view` and `linalg.subview` ops evolved into the standard dialect;
 - the `linalg.for`, `linalg.load` and `linalg.store` ops evolved into a prelude
 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.
 
 Given the evolution of the scope, it becomes apparent that a better name than
 "Linalg" could remove some of the confusions related to the dialect (and the
 underlying approach), its goals and limitations.
 
 ## Prior Art

 static knowledge and analyses will not be serious contenders for these problems.
 
 ## Key Observations<a name="keyobservation"></a>
 The following key observations have influenced the design of Linalg and helped
 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
 observation. When one designs IR for transformations, closed-ness is
 often a non-negotiable property.
 This is a key design principle of polyhedral IRs such as
 [URUK](http://icps.u-strasbg.fr/~bastoul/research/papers/GVBCPST06-IJPP.pdf)
 and

 ### Summary of Existing Alternatives a Picture<a name="observationssummary"></a>
 Lastly, we summarize our observations of lessons from [Prior
 Art](#prior-art)---when viewed under the lense of our [Core Guiding
 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.