## What
Makes the `tileops.trace` module documentation-ready and adds a usage
tutorial,
so the trace tool renders cleanly on the docs site (mkdocstrings +
Material).
- **Docstrings: Sphinx roles → plain code spans.** Across the whole
`tileops/trace/` package (`__init__`, `api`, `decode`, `markers`,
`passes`,
`record`, `state`, `ui`), replace `:func:` / `:class:` / `:mod:` /
`:data:`
cross-reference roles with double-backtick code spans. The project is
Google-docstring-only; mkdocstrings does not resolve Sphinx roles, so
they
rendered as literal `:func:`...`` text on the site.
- **`ui.py` timeline legend fix.** The horizontal legend overlapped the
x-axis
title. Give the x-axis title a `standoff`, anchor the legend below it
(`y: -0.30`, `yanchor: top`), and grow the bottom margin (120 → 170).
- **New tutorial: `docs/perf/trace-timeline.md`.** End-to-end
walkthrough —
write a traced warp-specialized GEMM, run it, enable tracing, read the
timeline. Each code block uses Material code annotations (the `+`
markers)
linked to the auto-generated API reference.
- **`docs/perf/README.md`**: add a "Tools & Guides" entry pointing at
the tutorial.
## Why
The trace tool shipped in #1638 with no rendered API docs or guide; this
makes
its public surface (`tileops.trace.api`) render correctly and gives
users a
single walkthrough.
## Notes
- No behavior change: docstring text and one Plotly layout dict only.
- The site-side wiring (mkdocstrings page, nav, embedded timeline) is a
separate
PR against `tile-ai/TileOPs.github.io`.
Closes#1639
2bcb708413