[Backline] fix transport/executor dialect docs

doc/code/dialects/Executor/ExecutorDialect.md

@@ -12,4 +12,11 @@ interacts with an executor service:
 * Dispatching a previously-shipped qnode kernel
 * Invoking an arbitrary symbol in a shared library
 
-[TOC]
+`dispatch-executor-targets` is what emits these ops. One caller is the `transport` dialect's
+bring-up: a [PennyLane](https://docs.pennylane.ai/en/stable/) `Placement` node marked as
+running out of process needs its code on the machine that runs it, which is what this dialect
+describes.
+
+> [!IMPORTANT]
+> The executor dialect is experimental and will not maintain API stability between
+> releases. Use at your own risk.

doc/code/dialects/Transport/TransportAttributes.md

@@ -0,0 +1,63 @@
+<!-- Autogenerated by mlir-tblgen; don't manually edit -->
+
+### BacklineAttr
+
+_A backline placement: one controller and the coprocessors it drives._
+
+Syntax:
+
+```
+#transport.backline<
+  mlir::StringAttr,   # transport
+  ::catalyst::transport::NodeAttr,   # controller
+  ::llvm::ArrayRef<::catalyst::transport::NodeAttr>   # coprocessors
+>
+```
+
+#### Parameters:
+
+| Parameter | C++ type | Description |
+| :-------: | :-------: | ----------- |
+| transport | `mlir::StringAttr` | transport carrying the traffic, selecting the compiled backend |
+| controller | `::catalyst::transport::NodeAttr` | the controller node that drives the session |
+| coprocessors | `::llvm::ArrayRef<::catalyst::transport::NodeAttr>` | the coprocessor nodes the controller drives |
+
+### NodeAttr
+
+_A backline participant: a controller or a coprocessor._
+
+Syntax:
+
+```
+#transport.node<
+  mlir::StringAttr,   # name
+  mlir::StringAttr,   # peer
+  mlir::IntegerAttr,   # oob_port
+  mlir::StringAttr,   # backend_lib
+  mlir::StringAttr,   # config
+  mlir::StringAttr,   # triple
+  mlir::StringAttr,   # address
+  mlir::StringAttr,   # symbol
+  mlir::BoolAttr,   # out_of_process
+  mlir::IntegerAttr,   # in_bytes
+  mlir::IntegerAttr,   # out_bytes
+  mlir::IntegerAttr   # work_item_idx
+>
+```
+
+#### Parameters:
+
+| Parameter | C++ type | Description |
+| :-------: | :-------: | ----------- |
+| name | `mlir::StringAttr` | this node's name; the session registry key when non-empty |
+| peer | `mlir::StringAttr` | the peer's address for the out-of-band handshake |
+| oob_port | `mlir::IntegerAttr` | TCP port for the out-of-band handshake |
+| backend_lib | `mlir::StringAttr` | backend plugin the runtime dlopens for this node |
+| config | `mlir::StringAttr` | backend configuration string, passed through verbatim |
+| triple | `mlir::StringAttr` | target triple this node's code is compiled for |
+| address | `mlir::StringAttr` | executor address when this node runs out of process |
+| symbol | `mlir::StringAttr` | coprocessor function symbol the backend binds |
+| out_of_process | `mlir::BoolAttr` | whether this node's code is dispatched to an executor rather than run in the compiling process |
+| in_bytes | `mlir::IntegerAttr` | request size in bytes for one round |
+| out_bytes | `mlir::IntegerAttr` | reply size in bytes for one round |
+| work_item_idx | `mlir::IntegerAttr` | index of this node's work item within the round |

doc/code/dialects/Transport/TransportDialect.md

@@ -9,118 +9,18 @@ between two endpoints: creating a session, bringing up the connection,
 exchanging memory handles, establishing a data path, and running rounds
 of request/reply traffic until teardown.
 
-This is what a Backline compiles to. A PennyLane `Placement` is serialized
-into the `catalyst.backline` module attribute, naming one controller and the
-coprocessors it drives; `inject-transport-session` reads that attribute and
-emits the session bring-up and teardown in terms of these ops,
-`lower-decode-to-transport` turns a decode into a request/reply round over
-the session, and `convert-transport-to-llvm` lowers the result to
-`__catalyst__transport__*` runtime calls. A node here is a Backline
-participant -- a controller or a coprocessor -- and the placement's
-transport selects which compiled backend carries the traffic.
-
-[TOC]
-
-## Attributes
-
-### BacklineAttr
-
-_A backline placement: one controller and the coprocessors it drives._
-
-Syntax:
-
-```
-#transport.backline<
-  mlir::StringAttr,   # transport
-  ::catalyst::transport::NodeAttr,   # controller
-  ::llvm::ArrayRef<::catalyst::transport::NodeAttr>   # coprocessors
->
-```
-
-#### Parameters:
-
-| Parameter | C++ type | Description |
-| :-------: | :-------: | ----------- |
-| transport | `mlir::StringAttr` | transport carrying the traffic, selecting the compiled backend |
-| controller | `::catalyst::transport::NodeAttr` | the controller node that drives the session |
-| coprocessors | `::llvm::ArrayRef<::catalyst::transport::NodeAttr>` | the coprocessor nodes the controller drives |
-
-### NodeAttr
-
-_A backline participant: a controller or a coprocessor._
-
-Syntax:
-
-```
-#transport.node<
-  mlir::StringAttr,   # name
-  mlir::StringAttr,   # peer
-  mlir::IntegerAttr,   # oob_port
-  mlir::StringAttr,   # backend_lib
-  mlir::StringAttr,   # config
-  mlir::StringAttr,   # triple
-  mlir::StringAttr,   # address
-  mlir::StringAttr,   # symbol
-  mlir::BoolAttr,   # out_of_process
-  mlir::IntegerAttr,   # in_bytes
-  mlir::IntegerAttr,   # out_bytes
-  mlir::IntegerAttr   # work_item_idx
->
-```
-
-#### Parameters:
-
-| Parameter | C++ type | Description |
-| :-------: | :-------: | ----------- |
-| name | `mlir::StringAttr` | this node's name; the session registry key when non-empty |
-| peer | `mlir::StringAttr` | the peer's address for the out-of-band handshake |
-| oob_port | `mlir::IntegerAttr` | TCP port for the out-of-band handshake |
-| backend_lib | `mlir::StringAttr` | backend plugin the runtime dlopens for this node |
-| config | `mlir::StringAttr` | backend configuration string, passed through verbatim |
-| triple | `mlir::StringAttr` | target triple this node's code is compiled for |
-| address | `mlir::StringAttr` | executor address when this node runs out of process |
-| symbol | `mlir::StringAttr` | coprocessor function symbol the backend binds |
-| out_of_process | `mlir::BoolAttr` | whether this node's code is dispatched to an executor rather than run in the compiling process |
-| in_bytes | `mlir::IntegerAttr` | request size in bytes for one round |
-| out_bytes | `mlir::IntegerAttr` | reply size in bytes for one round |
-| work_item_idx | `mlir::IntegerAttr` | index of this node's work item within the round |
-
-## Types
-
-### SessionType
-
-_An opaque transport session handle, tagged with its role._
-
-Syntax:
-
-```
-!transport.session<
-  ::catalyst::transport::Role   # role
->
-```
-
-#### Parameters:
-
-| Parameter | C++ type | Description |
-| :-------: | :-------: | ----------- |
-| role | `::catalyst::transport::Role` | an enum of type Role |
-
-### TokenType
-
-_A handle to an in-flight asynchronous step, awaited with transport.await._
-
-Syntax: `!transport.token`
-
-
-## Enums
-
-### Role
-
-_Transport session role_
-
-#### Cases:
-
-| Symbol | Value | String |
-| :----: | :---: | ------ |
-| Controller | `0` | controller |
-| Coprocessor | `1` | coprocessor |
+This is what a Backline compiles to. A [PennyLane](https://docs.pennylane.ai/en/stable/)
+`Placement` is serialized into the `catalyst.backline` module attribute, naming one
+controller and the coprocessors it drives; `inject-transport-session` reads that attribute
+and emits the session bring-up and teardown in terms of these ops,
+`lower-decode-to-transport` turns a decode into a request/reply round over the session, and
+`convert-transport-to-llvm` lowers the result to `__catalyst__transport__*` runtime calls.
+A node here is a Backline participant -- a controller or a coprocessor -- and the
+placement's transport selects which compiled backend carries the traffic.
+
+A node the placement dispatches to another machine is shipped and launched through the
+`executor` dialect, so a placement that mixes local and dispatched nodes uses both.
+
+> [!IMPORTANT]
+> The transport dialect is experimental and will not maintain API stability between
+> releases. Use at your own risk.

doc/code/dialects/Transport/TransportTypes.md

@@ -0,0 +1,25 @@
+<!-- Autogenerated by mlir-tblgen; don't manually edit -->
+
+### SessionType
+
+_An opaque transport session handle, tagged with its role._
+
+Syntax:
+
+```
+!transport.session<
+  ::catalyst::transport::Role   # role
+>
+```
+
+#### Parameters:
+
+| Parameter | C++ type | Description |
+| :-------: | :-------: | ----------- |
+| role | `::catalyst::transport::Role` | an enum of type Role |
+
+### TokenType
+
+_A handle to an in-flight asynchronous step, awaited with transport.await._
+
+Syntax: `!transport.token`

doc/code/dialects/executor.rst

@@ -1,4 +1,9 @@
 .. mdinclude:: Executor/ExecutorDialect.md
+   :end-line: -3
+
+.. important::
+   The executor dialect is experimental and will not maintain API stability between
+   releases. Use at your own risk.
 
 Types
 -----

doc/code/dialects/transport.rst

@@ -1,5 +1,20 @@
 .. mdinclude:: Transport/TransportDialect.md
+   :end-line: -3
 
+.. important::
+   The transport dialect is experimental and will not maintain API stability between
+   releases. Use at your own risk.
+
+
+Types
+-----
+
+.. mdinclude:: Transport/TransportTypes.md
+
+Attributes
+----------
+
+.. mdinclude:: Transport/TransportAttributes.md
 
 Operations
 ----------