Repository navigation
docs(book): put the book's Rust blocks on rustfmt's import order - #1241
Merged
nihalpasham merged 3 commits intoSep 6, 2026
Merged
Conversation
NVIDIA#1193 made `cargo oxide new` emit rustfmt-clean projects, because a scaffolded project failing its own first `cargo oxide fmt --check` is a bad first five minutes. The book's hand-written blocks kept the old order, so a reader who copies one into a project gets the same diff on the same command. Measured over every tracked book page, taking each ```rust block that contains a `cuda_*` import and running the pinned rustfmt at the book's edition: already rustfmt-clean 58 differ in imports only <- fixed here 15 differ in other formatting <- left alone 23 The 15 are the same two orderings NVIDIA#1193 fixed in the templates: crates not sorted (`cuda_device`/`cuda_host` ahead of `cuda_core`, and `cuda_async` where present), and `DisjointSlice` and friends after the lowercase items inside the braces rather than before them under style edition 2024. The 23 differ for reasons that have nothing to do with imports -- one parameter per line in a function signature, `{ /* ... */ }` split across two lines, a wrapped call collapsed. Reformatting deliberately laid-out teaching code is a different change with a different argument, so those blocks are untouched. Only rustfmt's import region is spliced back into each block, not its whole formatted output, so every non-import line stays byte-identical. Taking the whole block instead reflows that teaching code, which is what made the distinction worth drawing rather than assuming. Nothing catches this today: a markdown code block is compiled by nothing and formatted by nothing, and `check-book-api-names.sh` verifies that the device-API names the docs show exist, which is a different property and already passes. Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
nihalpasham
added
documentation
The first commit put 17 Rust blocks in 14 book pages on rustfmt's edition-2024 import order. 30 blocks in 12 pages still carried the old order (crates unsorted, uppercase names after lowercase ones). This splices rustfmt's output for the top-level `use` region into each of them, the same mechanism the first commit used: 16 whole-item blocks and 14 partial snippets whose `use` lines format on their own. Every changed line is a `use` statement or a brace-list continuation; no other line moved, so the one-param-per-line teaching layout stays. Also adds the `DisjointSlice` import the `reduce_dynamic` block in the shared-memory chapter used without importing, then formats that region. With both commits the book has one import order: 47 blocks in 18 pages changed, 0 blocks differ from `rustfmt --edition 2024` in their imports. Signed-off-by: nihalpasham <nihalp@nvidia.com>
A markdown block is compiled by nothing and formatted by nothing, which is how 47 blocks drifted from the order `cargo fmt` writes in an edition-2024 `cargo oxide new` project after the scaffold templates were fixed with a real-rustfmt test. scripts/check-book-import-order.sh walks every tracked ```rust block under cuda-oxide-book/, extracts each contiguous run of top-level `use` items, and runs `rustfmt --edition 2024 --check` on that region alone. It prints the page, the fence line and rustfmt's diff, and exits non-zero. Signatures, bodies and comments are never formatted, so teaching layout and partial snippets with no enclosing item cannot trip it. A `use` line rustfmt cannot parse is reported too. Parse self-test: at least 50 blocks with imports must be found. rustfmt comes from rust-toolchain.toml through the rustup proxy, as in fmt.yml, so the pinned nightly's order is the one checked. On the branch before the sweep the guard listed all 30 stale blocks in 12 pages; after it, 98 import regions in 98 blocks across 42 pages pass. Wired into status-guard.yml as `book-import-order` and into the Justfile's `check-guards` recipe, which mirrors that workflow. Signed-off-by: nihalpasham <nihalp@nvidia.com>
Collaborator
|
The splice mechanism is right and kept: rustfmt's import region back into the block, nothing else moved. After your commit, 30 blocks still carried the old order, including the landing block in index.md. What we stacked on your branch (your commit untouched underneath)
Validation: book builds under |
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.
Closes #1240. This is the follow-up invited in the #1193 review.
#1193 made
cargo oxide newemit rustfmt-clean projects. The book's hand-written blocks kept the old import order, so a reader who copies one into a project gets the same diff on the same firstcargo oxide fmt --check.Scope, measured
Over every tracked book page, taking each
```rustblock that contains acuda_*import and running the pinned rustfmt at the book's edition:After the change: 73 clean, 0 differing in imports, and the same 23 differing in other formatting as before.
The 15 are the two orderings #1193 fixed in the templates: crates not sorted (
cuda_device/cuda_hostahead ofcuda_core, andcuda_asyncwhere present), andDisjointSliceand friends after the lowercase items inside the braces instead of before them under style edition 2024.What is deliberately not touched
The 23 differ for reasons unrelated to imports — one parameter per line in a function signature,
{ /* ... */ }split across two lines, a wrapped call collapsed. Reformatting deliberately laid-out teaching code is a different change with a different argument, so those blocks are byte-identical here.Only rustfmt's import region is spliced back into each block, not its whole formatted output. That distinction is load-bearing: taking the whole block reflows the teaching code above, and I only found that out by diffing rather than trusting my own classifier. Verified afterwards by grepping the resulting diff for anything that is not a
usestatement or one of its continuation lines — nothing.A correction I owe on my own issue
The scope figures in #1240 as originally filed were wrong: it said 38 blocks and claimed every diff was imports-only. My measurement filtered rustfmt's
--checkoutput withstartswith("-"), but that output is colourised, so every changed line begins with an ANSI escape, nothing matched, and the "is every changed line an import?" test was vacuously true. 38 was really "blocks that differ from rustfmt for any reason". Re-measured with--color=never, corrected on the issue, and the table above is the corrected version.Why nothing catches this
A markdown code block is compiled by nothing and formatted by nothing.
scripts/check-book-api-names.shverifies that the device-API names the docs show exist, which is a different property and passes today, before and after.Test plan
sphinx-build -W --keep-going -b html cuda-oxide-book— build succeeded.scripts/check-book-api-names.sh,scripts/check-book-catalog-stamp.sh,scripts/check-spdx-headers.sh— pass.cuda-oxide-book/and only import lines.