[Docs] Add a development guide and a Blog section, lay out the indexes as cards, and reorder the API and Benchmarks pages - #61
Merged
Conversation
…tyle links in prose The Blog section holds technical explorations from building TileOPs. It starts with its index page only; posts are added to nav and to the index as they are published. The section is built from plain pages rather than Material's blog plugin: under mkdocs-static-i18n that plugin renders no posts and warns on its archive pages. hooks.py gives a post's subtitle its class, so no Markdown page carries styling. Home's introduction now states what TileOPs is for: a library designed for agents and built by them, held to code-quality requirements so the project stays maintainable, its results verifiable and its kernels tunable. Every link in running text carries an arrow, east within the site and north-east off it, and a teal wash on hover.
… and reorder the Benchmarks and API Reference pages The development guide is the first User Guide page. It covers getting the code, the dev image and a local install, when kernels compile, the test tiers, when a benchmark is needed, and the title, description and CI of a pull request. It names no image tag or version that a release would change; it links where they are kept instead. The Chinese page is the source; the English page follows it. The User Guide and Design indexes group their pages by topic, and each page shows as a card with a one-line description. The Markdown stays a plain list per group; hooks.py marks the lists and extra.css draws the cards. The nav follows the same order, and the Chinese label for User Guide is now 用户指南. The timeline trace guide was the one page without a Chinese version. It mirrors TileOPs docs/perf/trace-timeline.md, so the translation follows that file. The Benchmarks pages, and the API Reference nav after them, run in the order a reader meets the ops: Elementwise and RoPE, the reductions and normalizations, Conv & Pool, GEMM and Quantization, Attention, MoE and Sampling, then the sequence-mixing kernels. The workload key above each table lists one label per line, with what it ran on under it.
lcy-seso
added a commit
that referenced
this pull request
Oct 2, 2026
## Problems - `assets/extra.css` is served under the same URL whatever it contains, and GitHub Pages lets browsers cache it. A browser holding an older copy renders new markup without its styles: after #61 the User Guide cards showed as plain headings and lists until a hard refresh. ## Changes - `hooks.py` appends a hash of each local stylesheet's content to its `extra_css` URL in `on_config`, e.g. `assets/extra.css?v=93090c7963`, so the URL changes whenever the styles do. Entries that already carry a query or are not local files are left alone. - `CLAUDE.md` records that the hook versions the URL, so no one adds `?v=` by hand. - `mkdocs build` reports only `griffe:` warnings; the English and Chinese pages both link the versioned URL. `pytest` and `ruff` pass.
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.
Problems
tileops._FAMILIESorder, which splits ops a model uses together: RoPE far from Elementwise, Quantization before GEMM, MoE before Attention.performance-guides/trace-timelineis the one page without a Chinese version.Changes
user-guide/developmentas the first User Guide page, Chinese-authored with an English version: getting the code, the dev image and a local install, kernel compilation and caching, the test tiers, when a benchmark is needed, and the title, description and CI of a PR. It names no image tag or version a release would change, and links where they are kept.mkdocs-static-i18n.hooks.pymarks the lists andextra.cssdraws the cards.DATA_PAGES,_BENCH_ORDERand the API nav agree./api/topk/there in both locales throughon_post_build.performance-guides/trace-timelineinto Chinese, with the English page's anchors.Op Interface Referencenav translation.CLAUDE.md: the Blog section, card indexes, page order, redirects, link styling.mkdocs buildreports onlygriffe:warnings.pytest,ruff,stylelintandcheck_api_pages.pypass. Golden pages unchanged.