docs: restructure ROCm installation section and add vLLM adapter topic

[pmoutsias-amd]

Summary

• Restructures the README "ROCm installation" section into subsections and gives --devel its own.
• Adds the vLLM adapter page (docs/rocm-docs/engines/vllm.md) to the docs site and regroups the index and TOC.
• Adds a Getting started link to the approval gate.
• Applies further editorial changes: moves Demos under Getting started in the nav, adds an intro sentence to the Command reference page and swaps a reference URL in docs/vllm.md (the old rocmdocs.amd.com link now points to the AI ecosystem vLLM page, and the bare reference URLs become titled links).

Docs-only change: no scenario needed

This change is docs-only. It ships no behavioral change to the CLI, so no test scenario is required: nothing reddens if the change is reverted, and the -W docs build is the only thing that validates it. The one edit outside the docs tree is the CI docs: path filter, which extends an existing gate rather than adding behavior.

Test plan

• "Sphinx docs build (-W)" passes
• Install and Getting started pages render the README includes correctly
• vLLM adapter page appears in the nav

[siloteemu]

🔴 Automated review · pr-review-watcher · 9ab059d

This automation never files a GitHub approval, so no approving review will appear here whatever the outcome — the merge decision stays with a human reviewer.

Summary

Docs-only change: restructures the README install sdk prose into subsections plus an update flag table, adds a vLLM adapter page to the Sphinx site, and regroups the index grid and TOC. Outcome: Needs work — one gate hole introduced by the new page. Verified: the docs build and the full suite were not run here; instead I checked every {include} :start-after:/:end-before: marker in the changed files against README.md and confirmed each matches exactly once and pulls the intended range, confirmed every added link, :doc: target and #anchor resolves to a real file and a heading that lands inside the included range, confirmed the base tip equals the merge base so nothing here is base drift, and confirmed against the Rust sources that every claim in the rewritten README section — including all six rows of the new update flag table, checked row-by-row against the clap requires/conflicts_with attributes — is accurate and that the rewrite drops no claim from the old prose. Checks at review time: 19 success, 10 skipped, 0 pending, 0 failure. Blocking: 1 · Non-blocking: 5.

🚫 Blocking (must fix before merge)

.github/workflows/ci.yml:169-174 — the docs path filter was not extended for the file this PR newly pulls into the docs build. Its own comment states the rule: "the doc sources themselves, plus README.md and CONTRIBUTING.md, which several pages single-source via MyST {include} directives". This PR adds a third such single-sourced file: docs/rocm-docs/engines/vllm.md:7 is nothing but {include} ../../vllm.md, so docs/vllm.md becomes a build input for the first time (before this PR it was only named as literal text in install/installation.md, never transcluded). The filter list still covers only docs/rocm-docs/**, README.md, CONTRIBUTING.md, .readthedocs.yaml and .github/workflows/**.

Why it blocks: docs-build is the -W Sphinx job and is this PR's own stated test plan — it is the only thing that validates the new page. With the filter unchanged, a later PR that edits only docs/vllm.md skips that job entirely, so a broken include marker, a malformed directive or a heading change in a long, actively-edited file merges green and surfaces afterwards as a failure on main or on an unrelated PR. That is a self-inflicted hole in the gate this change depends on, and this PR is the change that opens it. This is the parallel-site shape: the new include landed in one place and its counterpart in the filter did not.

Fix: add - 'docs/vllm.md' to the docs: filter list alongside README.md and CONTRIBUTING.md, and extend the comment above it to name the third single-sourced file so the next person adding a transcluded page outside docs/rocm-docs/ sees the obligation.

Per-commit notes

• 910eefe2 — the substantive commit: splits the README install sdk prose into --devel / Approval prompt / Install location / Driver installation / Updates / ROCm 10 subsections and converts the update flag prose into a table; adds docs/rocm-docs/engines/vllm.md transcluding docs/vllm.md; regroups index.rst and _toc.yml.in (Demos moves under Getting started, "Commands" becomes "Use ROCm CLI"); adds the Getting started cross-link to the approval gate and a newly surfaced glibc paragraph on the install page; restructures and rewords docs/vllm.md.
• 81b8c7e3 — reorders the "Use ROCm CLI" entries so Command reference precedes vLLM adapter and pins the entry title. Touches only _toc.yml.in, not the matching index.rst card (see non-blocking item 1).
• 9ab059d1 — adds a two-sentence orientation paragraph to commands.md with a link to Getting started; the link and the page it points at both resolve.

Non-blocking

• docs/rocm-docs/index.rst:40-41 — the landing-page card lists vLLM adapter before Command reference while sphinx/_toc.yml.in:13-16 lists them the other way, so the sidebar and the homepage disagree; commit 81b8c7e3 exists to set that order and applied it to only one of the two sites. Swap the two :doc: lines.
• docs/vllm.md:16-17 — the relocated Windows paragraph drops its closing sentence "No CPU fallback is used."; the policy still appears at line 12 ("does not run CPU mode") and line 120, so nothing is factually lost, but the reinforcement disappears from exactly the spot where a Windows reader is told to go elsewhere.
• docs/vllm.md — the prose product name is swept from rocm-cli to ROCm CLI in this one file, leaving it out of step with every sibling under docs/ (testing, release-trust, wsl, llm-tool-use, manual-testing and others still use the lowercase form in prose); either say in the PR text that this is a deliberate first file or follow up to normalise the rest.
• docs/rocm-docs/getting-started.md:17-29 — the new block mirrors a README sentence into the page and then re-includes using that same sentence as :start-after:, which reads as a self-referential anchor until you confirm the identical text also lives in README.md:206-210. It resolves correctly, and the pattern is pre-existing, but it misleads on first read and will do so again; a one-line HTML comment above the block saying the prose is a deliberate copy of the README sentence with the link retargeted would prevent the re-read.
• PR description — the contributor rules ask a docs-only change to say in the PR text why no scenario is needed; the body omits that line, and folds the Demos nav move, the may→might wording change and the reference-URL swap into a generic "editorial changes" bullet. Otherwise the body is accurate: nothing it claims is absent from the diff.

Standing note on tests: this change adds and alters no test, and nothing reddens if it is reverted — there is no defect being fixed, and the -W docs build passes on both sides. The blocking item above is precisely about keeping that build reachable.

[siloteemu]

🔴 Automated review · pr-review-watcher · 9ab059d

Requesting changes on one item from the round posted alongside this review. Everything else in that round is non-blocking.

The docs path filter was not extended for the file this change newly pulls into the docs build.

docs/rocm-docs/engines/vllm.md is nothing but a MyST {include} of docs/vllm.md, so that file becomes a build input for the first time — before this change it was only named as literal text on the install page, never transcluded. The docs: path filter in the CI workflow still lists only docs/rocm-docs/**, README.md, CONTRIBUTING.md, .readthedocs.yaml and .github/workflows/**, and the filter's own comment states the rule it is meant to encode: the doc sources plus the files that pages single-source via {include} directives. This change adds a third such file and does not list it.

Why this blocks rather than being a note: the -W Sphinx build is conditioned directly on that filter, and it is this change's own stated test plan — it is the only thing validating the new page. With the filter unchanged, a later pull request that edits only docs/vllm.md skips the job entirely, so a broken include marker, a malformed directive or a heading change in a long and actively edited file merges green and surfaces afterwards as a failure on the default branch or on an unrelated pull request. This change is the one that opens that hole, and a gap like this is not revisited once it has landed.

Resolving it: add docs/vllm.md to the docs: filter list alongside README.md and CONTRIBUTING.md, and extend the comment above the list to name it, so the next person adding a transcluded page from outside the docs tree sees the obligation.

Checks at review time: 19 success, 10 skipped, 0 pending, 0 failure. The docs build was not run here; the finding rests on reading the filter, the job's condition and the new include together.

[juhovainio]

Nice cleanup of the install section and good to see the vLLM adapter land in the built docs site. Two things worth fixing before merge, left inline below — neither is about the prose itself, both are about wiring that this PR changes.

[juhovainio]

This file {include}s docs/vllm.md into the built Sphinx site for the first time, but .github/workflows/ci.yml's docs: path filter (around lines 165-174) only watches docs/rocm-docs/**, README.md, CONTRIBUTING.md, .readthedocs.yaml, and .github/workflows/** — it doesn't list docs/vllm.md. A future PR that edits docs/vllm.md alone (a broken include, a bad code fence) won't trigger the "Sphinx docs build (-W)" check that would catch it, even though this page now ships in the site. Worth adding docs/vllm.md to the docs: filter list.

[pmoutsias-amd]

Thanks @juhovainio. I've added docs/vllm.md to the path filter in .github/workflows/ci.yml and extended the comment above it.

[juhovainio]

After the second commit reorders docs/rocm-docs/sphinx/_toc.yml.in to list commands before engines/vllm ("Command reference is the more common lookup target"), this landing-page grid card still lists vLLM adapter before Command reference — so the sidebar and the index page now disagree on which one comes first. Worth swapping these two lines to match the TOC order, or dropping the TOC reorder commit's rationale if vLLM-first is actually intended here.

[pmoutsias-amd]

Thanks @juhovainio, I updated card order so Command reference precedes vLLM adapter, matching the _toc.yml.in reorder.

[pmoutsias-amd]

Reviewer feedback addressed

• CI docs: filter: added docs/vllm.md to the path filter in .github/workflows/ci.yml and extended the comment above it. docs/rocm-docs/engines/vllm.md transcludes docs/vllm.md, making it a build input for the first time. Without this, a later edit to that file alone would skip the -W build that catches a broken include.
• index.rst card order: swapped so Command reference precedes vLLM adapter, matching the _toc.yml.in reorder. The sidebar and landing page now agree.
• docs/vllm.md Windows paragraph: restored "No CPU fallback is used.", dropped in the restructure.
• getting-started.md anchor: added a comment explaining the prose is a deliberate copy of the README sentence, reused as the next :start-after: anchor.

[anisha-amd]

Review complete, minor suggestions

[juhovainio]

Looks like the batch-apply of anisha-amd's suggestion comments (the "Apply batched suggestions from code review" commit) didn't fully replace the original text in four spots — it inserted the rewritten line(s) right after the original instead of swapping them, so the docs now show the same sentence twice back-to-back. Left inline comments at each spot. Everything else in this round (ci.yml docs: path filter, README table header, index.rst card order) looks correctly applied.

[juhovainio]

This duplicates the previous two lines ("You can also serve any compatible Hugging Face model directly — see / [Model serving]... for the GGUF-vs-safetensors rule,") with slightly different wording ("directly. See" vs "directly — see"). The old pair is still there right above as unchanged context — only one of the two should remain. Note the code comment a few lines up says to edit this sentence in lockstep with README.md's copy; README.md's own copy (git show 409ff164:README.md around "You can also serve") wasn't touched, so whichever version you keep here, please re-sync it with README.md too.

[juhovainio]

Same pattern: these 4 lines duplicate the paragraph right above ("runtime. Two installers write torch...") with minor wording changes (em dash → colon, "so" → "So."). The original paragraph is still present as unchanged context immediately before this hunk.

[juhovainio]

Partial duplicate: line 62 ("Use it when you are deliberately running a torch the alignment would replace — a", unchanged context) is immediately followed by this added line repeating the same sentence opening ("...replace (a"). Looks like only the second line of the original two-line paragraph was swapped out; the first line should have been replaced too, not kept.

[juhovainio]

Same pattern again: this line repeats the context line directly above it ("model more KV cache. Applies to vLLM only — it is ignored, with a note in the") with an em dash → semicolon change. One of the two needs to go.

[pmoutsias-amd]

Thanks @juhovainio for flagging the issue with the batch apply. I've removed the instances of duplicated text.

[juhovainio]

The latest commit (d051e18) correctly fixes all four duplicate-line spots I flagged in the last round — checked each one against the actual diff, and they're clean swaps, not a one-sided removal. The README.md sentence is also re-synced with its getting-started.md copy, which was the one loose end from before. Looks good to merge.

Blockers have been implemented.