Scale ops docs: TensorOps surface scan + human-prose partials (#511)

build-logic/convention/src/main/kotlin/GenerateDocumentationTask.kt

@@ -268,14 +268,24 @@ abstract class GenerateDocumentationTask : DefaultTask() {
             appendLine("")
             appendLine("Modality: ${operator.modality.capitalize()}")
             appendLine("")
-            
+
             operator.functions.forEach { function ->
-                generateFunctionSection(function, this)
+                generateFunctionSection(operator, function, this)
             }
         })
     }
-
-    private fun generateFunctionSection(function: FunctionDoc, builder: StringBuilder) {
+
+    /**
+     * Per-function section layout fuses auto-derived facts (signature,
+     * parameters, return type, backend matrix) with optional hand-written
+     * prose pulled from a partial at
+     * `partials/ops/<operator>/<function>.adoc`. The partial is sliced by
+     * AsciiDoc tags — `math`, `intuition`, `examples`, `references` — so a
+     * single file per function carries all the human content, and missing
+     * tags render as empty via `optional`, keeping un-prosed ops valid.
+     */
+    private fun generateFunctionSection(operator: OperatorDoc, function: FunctionDoc, builder: StringBuilder) {
+        val partialBase = "ops/${operator.name.lowercase()}/${function.name.lowercase()}.adoc"
         builder.apply {
             appendLine("== ${function.name}")
             appendLine("")
@@ -286,7 +296,7 @@ abstract class GenerateDocumentationTask : DefaultTask() {
             appendLine(function.signature)
             appendLine("----")
             appendLine("")
-            
+
             if (function.parameters.isNotEmpty()) {
                 appendLine("=== Parameters")
                 appendLine("")
@@ -298,16 +308,32 @@ abstract class GenerateDocumentationTask : DefaultTask() {
                 }
                 appendLine("")
             }
-            
+
             appendLine("=== Return Type")
             appendLine("")
             appendLine("`${function.returnType}`")
             appendLine("")
-
+
+            // Human prose: math first so LaTeX sits right under the signature,
+            // then intuition and examples before the backend table, references
+            // last. All optional — ops with no partial still render cleanly.
+            appendLine("=== Definition")
+            appendLine("")
+            appendLine("include::partial\$$partialBase[tag=math,optional]")
+            appendLine("")
+            appendLine("=== Intuition")
+            appendLine("")
+            appendLine("include::partial\$$partialBase[tag=intuition,optional]")
+            appendLine("")
+            appendLine("=== Examples")
+            appendLine("")
+            appendLine("include::partial\$$partialBase[tag=examples,optional]")
+            appendLine("")
+
             if (includeBackendStatus.getOrElse(true) && function.statusByBackend.isNotEmpty()) {
                 generateBackendStatusTable(function, this)
             }
-            
+
             if (function.notes.isNotEmpty()) {
                 appendLine("=== Notes")
                 appendLine("")
@@ -316,7 +342,10 @@ abstract class GenerateDocumentationTask : DefaultTask() {
                     appendLine("")
                 }
             }
-
+
+            appendLine("=== References")
+            appendLine("")
+            appendLine("include::partial\$$partialBase[tag=references,optional]")
             appendLine("")
         }
     }

docs/modules/ROOT/pages/explanation/theory/matmul.adoc

@@ -1,41 +1,28 @@
 = Matrix Multiplication Theory
 
+The theory and intuition below are the single source of truth for `matmul`
+and are also embedded into the generated operator reference at
+xref:reference/operators/generated/tensorops.adoc#matmul[TensorOps.matmul].
+
 [#matmul-definition]
 == Mathematical Definition
 
-Matrix multiplication is a binary operation that produces a matrix from two matrices.
-Given two matrices A ∈ ℝ^(m×k) and B ∈ ℝ^(k×n), the matrix product C = AB is defined as:
-
-[stem]
-++++
-C_{ij} = \sum_{l=1}^{k} A_{il} \cdot B_{lj}
-++++
-
-Where:
-- C ∈ ℝ^(m×n) is the resulting matrix
-- i ranges from 1 to m (row index)
-- j ranges from 1 to n (column index)
-- l is the summation index over the shared dimension k
+include::partial$ops/tensorops/matmul.adoc[tag=math]
 
 [#matmul-properties]
-== Properties
-
-* **Associativity**: (AB)C = A(BC)
-* **Distributivity**: A(B + C) = AB + AC and (A + B)C = AC + BC
-* **Non-commutativity**: Generally AB ≠ BA
-* **Identity element**: AI = IA = A where I is the identity matrix
+== Intuition and Properties
 
-[#matmul-complexity]
-== Computational Complexity
-
-* Standard algorithm: O(mnk) operations
-* Strassen's algorithm: O(n^2.807) for square matrices
-* Current best known: O(n^2.373) (theoretical)
+include::partial$ops/tensorops/matmul.adoc[tag=intuition]
 
 [#matmul-applications]
 == Applications
 
 * Neural network forward pass computations
 * Linear transformations in computer graphics
 * Solving systems of linear equations
-* Principal component analysis (PCA)
+* Principal component analysis (PCA)
+
+[#matmul-references]
+== References
+
+include::partial$ops/tensorops/matmul.adoc[tag=references]

docs/modules/ROOT/pages/reference/operators/generated/index.adoc

@@ -1,11 +1,12 @@
 = AI-NET Operators Reference
 
-Generated from version `1.0.0` on 2026-04-13
+Generated from version `1.0.0` on 2026-04-14
 
 == Operators by Modality
 
 === Core
 
+* xref:reference/operators/generated/tensorops.adoc[TensorOps]
 * xref:reference/operators/generated/voidtensorops.adoc[VoidTensorOps]
 
 === Composite

docs/modules/ROOT/pages/reference/operators/generated/similarity.adoc

@@ -23,6 +23,18 @@ fun cosineDistance(other:Tensor, dim:Int, eps:Double): Tensor
 
 `Tensor`
 
+=== Definition
+
+include::partial$ops/similarity/cosinedistance.adoc[tag=math,optional]
+
+=== Intuition
+
+include::partial$ops/similarity/cosinedistance.adoc[tag=intuition,optional]
+
+=== Examples
+
+include::partial$ops/similarity/cosinedistance.adoc[tag=examples,optional]
+
 === Backend Support
 
 [cols="1,1,3", options="header"]
@@ -37,4 +49,7 @@ fun cosineDistance(other:Tensor, dim:Int, eps:Double): Tensor
 
 TIP: *all*: 
 
+=== References
+
+include::partial$ops/similarity/cosinedistance.adoc[tag=references,optional]