[Docs] Address every op by its public two-level path, tileops.<family>.<Op> - #41
Merged
Merged
Conversation
…ectly The API Reference nav and the index table were ordered along the stack a reader works through, which put the dense matmul and attention ahead of the pointwise and reduction primitives they are built from. Order both by how much an op composes instead: pointwise transforms, then the axis reductions and the normalizations built on them, then the matmul, then the windowed and spectral transforms, then the sequence-model kernels. mHC and Trace come last — one is a single algorithm, the other a tool rather than an op. This is the order `tileops.ops.__all__` now uses, so the two can be read side by side. Within the GEMM page, dense GEMM now comes before batched, matching the same rule. MHC was captioned "multi-head compression" on its page and in the index table. It stands for Manifold-Constrained Hyper-Connections, and the paper writes the abbreviation `mHC`. Correct both, and use `mHC` in the nav. The index example constructed `GemmOp`, which is not a name `tileops.ops` exports. Use `GemmFwdOp`.
Every API page named ops by the module they are implemented in: `::: tileops.ops.elementwise.activations.HardtanhFwdOp`. TileOPs now gives each family a module of its own, so an op is two levels deep and the second level is the family. Rewrite all 176 identifiers to `tileops.<family>.<Op>`, which is also what the rendered headings and anchors now read. The examples on the other user-facing pages move with them: the home page and the API reference index (both of which constructed `GemmOp`, a name TileOPs does not export), the torch.compile page, and the backend page, which reached into `tileops.ops.norm.rms_norm`. Adding an op now touches two `__init__` lists, not one — the family package where the class is implemented and the family module that is the public path. Step 2 of the add-op guide says so in both languages; without the second, an op is unreachable and the API reference cannot collect it. Eighteen public names had no page at all, which mattered less while `tileops.ops` was the documented path and they could at least be found there. Two pages and one section cover them: MoE, eleven ops — the fused FFN and the routing, layout and expert-GEMM stages it is built from; Engram, the GateConv pair and its decode step; and the three elementwise template base classes, at the end of that page, since a reader looking up `relu` should not meet them first. That leaves one public name undocumented, `MeanPoolingForwardOp`, which is in-tree only until it has a manifest entry. Anchors change with the identifiers: `#tileops.ops.elementwise.arithmetic.AddFwdOp` becomes `#tileops.elementwise.AddFwdOp`. Nothing in either repo links to the old form. Needs the TileOPs change on main first — until then mkdocstrings cannot resolve `tileops.<family>`. Built clean against that branch: 16.7 s, no unresolved identifier, and every one of the 193 documented ops rendered — 216 anchors on the elementwise page, 33 on MoE, 9 on Engram.
`MeanPoolingForwardOp` is public and now has a manifest entry, so it has a docstring worth rendering and belongs on an API page. It is the one op on the pooling page with no PyTorch counterpart: it averages the sequence axis of a `[batch, seq, heads, dim]` tensor in fixed-size chunks and can follow ragged sequence boundaries, so it gets a section of its own rather than sitting under average pooling. Needs the TileOPs manifest entry on main first — until then the class carries no docstring for the page to render.
The paired TileOPs change settled which families exist and what they hold, and this page set follows it: - `attention_indexing` is gone: the FP8 lightning indexer and the top-k selector were the same family, and both are now `tileops.attention`. Each keeps the page it was on — a page groups by topic, not by family. - `tileops.fp8_quant` becomes `tileops.quantization`, and dropout is `tileops.elementwise`. - The abstract bases are no longer public, so the elementwise page loses the template base-class section and the reduction page loses `CumulativeOp`. The API reference documents ops a caller can import. - The MoE page loses `MoePermuteNopadFwdOp` and `MoeUnpermuteFwdOp`, removed upstream in [Refactor][MoE] Remove legacy permute compatibility (tile-ai/TileOPs#2031), and its intro no longer describes a tight layout that a routing op produces, since only the padded one has one.
There was a problem hiding this comment.
Pull request overview
Updates the documentation site’s API reference to match TileOPs’ new public two-level operator paths (tileops.<family>.<Op>), expands coverage for newly public operator families, and reorders navigation/indexing to reflect composition order rather than “stack order”.
Changes:
- Rewrites mkdocstrings
:::identifiers across API pages to use the publictileops.<family>.<Op>paths, and corrects a few public import examples (tileops.norm,tileops.gemm). - Reorders the API Reference nav and API index table to follow
tileops._FAMILIEScomposition order; fixes mHC naming/captioning. - Adds missing public-op coverage via new MoE and Engram API pages, plus a chunked sequence mean section in pooling.
Reviewed changes
Copilot reviewed 27 out of 27 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Reorders API Reference nav; adds MoE/Engram entries and updates i18n nav translations (mHC/MoE/Engram). |
| docs/torch-compile.zh.md | Updates RMSNorm import path to tileops.norm. |
| docs/torch-compile.md | Updates RMSNorm import path to tileops.norm. |
| docs/new-op.zh.md | Updates “add an op” guidance to reflect new two-location export requirement (ops/<family>/__init__.py + <family>.py). |
| docs/new-op.md | Updates “add an op” guidance to reflect new two-location export requirement (ops/<family>/__init__.py + <family>.py). |
| docs/index.zh.md | Fixes home-page example to use GemmFwdOp on the public tileops.gemm path. |
| docs/index.md | Fixes home-page example to use GemmFwdOp on the public tileops.gemm path. |
| docs/backends.zh.md | Updates example import to use tileops.norm public path. |
| docs/backends.md | Updates example import to use tileops.norm public path. |
| docs/api/topk.md | Switches Top-k mkdocstrings identifier to tileops.attention.TopkSelectorFwdOp. |
| docs/api/rope.md | Switches RoPE mkdocstrings identifiers to tileops.rope.*. |
| docs/api/reduction.md | Switches reduction mkdocstrings identifiers to tileops.reduction.* and removes the abstract base entry in favor of concrete ops. |
| docs/api/quantization.md | Switches FP8 quant mkdocstrings identifier to tileops.quantization.FP8QuantFwdOp. |
| docs/api/pool.md | Switches pooling mkdocstrings identifiers to tileops.pool.* and adds chunked sequence mean op section. |
| docs/api/normalization.md | Switches norm mkdocstrings identifiers to tileops.norm.*. |
| docs/api/moe.md | Adds MoE API page using public tileops.moe.* identifiers. |
| docs/api/mhc.md | Renames page/title to mHC and switches mkdocstrings identifiers to tileops.sequence_modeling.*. |
| docs/api/mamba.md | Switches Mamba mkdocstrings identifiers to tileops.mamba.*. |
| docs/api/linear-attention.md | Switches Linear Attention mkdocstrings identifiers to tileops.linear_attention.* and updates covered ops list accordingly. |
| docs/api/linear-algebra.md | Reorders GEMM sections (Dense before Batched) and switches mkdocstrings identifiers to tileops.gemm.*. |
| docs/api/index.md | Updates API index snippet/import to tileops.gemm.GemmFwdOp and rewrites page ordering description/table. |
| docs/api/fft.md | Switches FFT mkdocstrings identifier to tileops.fft.FFTC2CFwdOp. |
| docs/api/engram.md | Adds Engram API page using public tileops.sequence_modeling.* identifiers. |
| docs/api/elementwise.md | Switches elementwise mkdocstrings identifiers to tileops.elementwise.*. |
| docs/api/dropout.md | Switches dropout mkdocstrings identifier to tileops.elementwise.DropoutFwdOp. |
| docs/api/convolution.md | Switches convolution mkdocstrings identifiers to tileops.convolution.*. |
| docs/api/attention.md | Switches attention mkdocstrings identifiers to tileops.attention.* (including FP8 lightning indexer section). |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
9
to
13
| import torch | ||
| from tileops.ops import GemmOp | ||
| from tileops.gemm import GemmFwdOp | ||
|
|
||
| op = GemmOp() # construct once, reuse | ||
| op = GemmFwdOp() # construct once, reuse | ||
| d = op(a, b) # the specialized kernel is built on first call |
`DropoutFwdOp` is `family: elementwise` and imported as `tileops.elementwise`, and it was the only op in that family with a page to itself — a page holding one op while the elementwise page holds nine sections. It joins the Activations section, and the nav is fifteen pages rather than sixteen.
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
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.
Pairs with tile-ai/TileOPs#2029, now on main.
problems
::: tileops.ops.elementwise.activations.HardtanhFwdOp. TileOPs now gives each family a module of its own, so the documented path is two levels.mHC.GemmOp, a name TileOPs does not export. The index claimed the linear-attention page covers KDA, which no op is. The backend page reached intotileops.ops.norm.rms_norm.changes
:::identifier totileops.<family>.<Op>. Rendered headings and anchors read the same way:#tileops.ops.elementwise.arithmetic.AddFwdOpbecomes#tileops.elementwise.AddFwdOp. Nothing in either repo links to the old form.tileops._FAMILIESorder: pointwise transforms, then the axis reductions and the normalizations built on them, then the matmul and the expert routing over it, then the windowed and spectral transforms, then the sequence-model kernels. Dense GEMM now precedes batched on its page. Pages group by topic rather than one per family — the FP8 lightning indexer is a section of the Attention page, and the sequence-modeling family is two pages, being two unrelated algorithms.tileops.attention, quantization istileops.quantization, dropout istileops.elementwise. Dropout had the only page holding a single op of a family that has a page of its own, so it joins the elementwise page's Activations section and the nav is fifteen pages.CumulativeOp; andMoePermuteNopadFwdOpandMoeUnpermuteFwdOp, removed in [Refactor][MoE] Remove legacy permute compatibility TileOPs#2031.GemmFwdOpon the home page and the API index,tileops.normon the torch.compile and backend pages, and the linear-attention row says what the page holds.__init__lists. The add-op guide's file table and its registration step say so in both languages; without the second, an op is unreachable and the API reference cannot collect it.verification
mkdocs buildagainst the merged TileOPs main: exit 0, and the gate this repo's CI applies — every^WARNINGthat is notgriffe:— reports nothing. 44 griffe warnings remain, unchanged frommain: 22 unique across en and zh, allNo type or annotationin TileOPs files this PR does not touch, which is the classchecks.ymldeliberately excludes.Rendered anchors: elementwise 210, MoE 27, Engram 9, pool 39.