docs: port v0.1.0 doc restructure from main (PR #473)

.github/workflows/ci.yml

@@ -160,13 +160,14 @@ jobs:
               - 'ruff.toml'
               - 'PSScriptAnalyzerSettings.psd1'
               - '.github/workflows/**'
-            # Sphinx docs site: the doc sources themselves, plus README.md and
-            # CONTRIBUTING.md, which several pages single-source via MyST
-            # `{include}` directives, plus the build config/toolchain pins.
+            # Sphinx docs site: the doc sources themselves, plus README.md,
+            # CONTRIBUTING.md and docs/vllm.md, which pages single-source via
+            # MyST `{include}` directives, plus the build config/toolchain pins.
             docs:
               - 'docs/rocm-docs/**'
               - 'README.md'
               - 'CONTRIBUTING.md'
+              - 'docs/vllm.md'
               - '.readthedocs.yaml'
               - '.github/workflows/**'
 

README.md

@@ -40,6 +40,9 @@ Live dashboard telemetry requires Linux or WSL2 (see
 [Interactive interfaces](#interactive-interfaces)). vLLM serving is Linux or WSL2
 only (see [docs/vllm.md](docs/vllm.md)).
 
+ROCm CLI supports multiple ROCm versions: 7.14, 10.0, and 10.1. ROCm 10.0 and
+later use a different install path; see [ROCm 10 and newer](#rocm-10-and-newer).
+
 The minimum supported Linux release, native or under WSL2, is Ubuntu 24.04. On
 other distributions the equivalent requirement is glibc 2.38 with
 `GLIBCXX_3.4.32`: that is what the Lemonade engine is linked against, and every
@@ -216,7 +219,7 @@ rocm serve qwen
 ```
 
 `qwen` is a built-in alias for a small assistant model that serves out of the
-box. You can also serve any compatible Hugging Face model directly — see
+box. You can also serve any compatible Hugging Face model directly. See
 [Model serving](#model-serving) for the GGUF-vs-safetensors rule, since which
 form works depends on the engine your GPU selects.
 
@@ -317,13 +320,13 @@ by rocm-cli.
 If no managed runtime is the active default, `install sdk` doesn't prompt.
 Otherwise it asks first, because the new install becomes the active default.
 The prompt applies to any install, including a `--family` or `--channel` you
-haven't installed before.
+haven't installed before, just as it does for a same-family upgrade.
 
 To approve without a prompt, for example in scripts or CI, where the prompt
 would otherwise refuse:
 
-- `--approve-replacing-active-default` approves the change of active default
-  only. The refusal message recommends it, and ROCm CLI's own non-interactive
+- `--approve-replacing-active-default` approves the change of active default.
+  The refusal message recommends it, and ROCm CLI's own non-interactive
   surfaces (chat, MCP, and the dashboard) pass it.
 - `--yes` gives the same approval and also approves installing required system
   packages, such as OpenMPI for vLLM. That requires `sudo`, so use it only where
@@ -338,8 +341,8 @@ same-version reinstall reuses the same root.
 
 `--prefix` changes this. The folder you name is used as-is for every version, so
 successive installs into one prefix replace each other in place. If the venv
-already there no longer runs its own Python, it is removed outright and rebuilt. The
-approval prompt doesn't cover this, because it asks only about changing the
+already there no longer runs its own Python, it is removed outright and rebuilt.
+The approval prompt doesn't cover this, because it asks only about changing the
 active default runtime, not about what a named prefix loses.
 
 #### Driver installation
@@ -351,21 +354,24 @@ package.
 
 `update` checks for a newer ROCm package.
 
-| Flag | Effect |
+| Flag | Description |
 | --- | --- |
-| `--apply` | Installs the update. Needs no approval flag, because selecting a runtime to update is the approval. Leaves the active default alone unless you add `--activate`. |
+| `--apply` | Installs the update. Never prompts and needs no approval flag, because selecting a runtime to update is the approval. Leaves the active default alone unless you add `--activate`. |
 | `--dry-run` | Previews what `--apply` would do without changing anything. Doesn't require `--apply`. |
 | `--runtime`, `--activate` | Require `--apply` or `--dry-run`. |
 | `--json` | Prints the check result as a single line of JSON instead of text. Conflicts with `--apply` and `--dry-run`. |
 | `--timeout-secs` | Bounds the network calls of the check. Requires `--json`. Conflicts with `--apply`. |
 | `--yes` | Accepted for consistency with other mutating commands, but grants nothing on `update`. The approval line the update path prints never credits it. |
 
-ROCm 10 and newer ship from a different source layout. You opt in by passing two
-things together: pin the version with `--version`, and name the exact GPU arch,
-using the raw `gfx` code rather than a family label:
+#### ROCm 10 and newer
+
+ROCm 10.0, and newer ship from a different source layout. ROCm 7.14
+uses the existing release and nightly sources. You opt in to ROCm 10 and newer by
+passing two things together: pin the version with `--version`, and name the exact
+GPU arch, using the raw `gfx` code rather than a family label:
 
 ```
-rocm install sdk --version 10.0.0 --family gfx1200 --dry-run
+rocm install sdk --version 10.1.0 --family gfx1200 --dry-run
 ```
 
 A family label such as `--family gfx120X-all` is rejected for those versions
@@ -378,9 +384,10 @@ torchaudio from their published dependency metadata, then validates that every
 selected framework package carries the same ROCm build identifier before it
 creates or changes a managed runtime.
 
-Without a `--version` of 10 or newer, `install sdk` resolves the same release
-and nightly sources as before. It doesn't retry against the ROCm 10 sources when
-a lookup finds nothing; it tells you what it couldn't find instead.
+Nothing about this happens on its own. Without a `--version` of 10 or newer,
+`install sdk` resolves the same release and nightly sources as before. It doesn't
+quietly retry against the ROCm 10 sources when a lookup finds nothing; it tells
+you what it couldn't find instead.
 
 ### Runtime management
 

docs/rocm-docs/commands.md

@@ -6,6 +6,10 @@ SPDX-License-Identifier: MIT
 
 # Command reference
 
+This page describes each `rocm` command, its options, and what it does. For a
+short list of the commands and what each is for, see
+[Getting started](getting-started.md).
+
 ```{include} ../../README.md
 :start-after: "## Commands"
 :end-before: "and a chat tab backed by any configured provider."

docs/rocm-docs/conf.py

@@ -65,6 +65,9 @@ def filter(self, record: logging.LogRecord) -> bool:
 # expected depth; docutils re-normalizes this in the rendered output, so it's
 # cosmetic here.
 suppress_warnings = ["etoc.toctree", "myst.header"]
+# rocm-docs-core defaults to 3, which skips the `####` "ROCm 10 and newer"
+# heading that installation.md links to.
+myst_heading_anchors = 4
 external_toc_path = "./sphinx/_toc.yml"
 external_projects_current_project = "rocm-cli"
 # No page here cross-references another ROCm project via intersphinx, and the

docs/rocm-docs/engines/vllm.md

@@ -0,0 +1,8 @@
+<!--
+Copyright © Advanced Micro Devices, Inc., or its affiliates.
+
+SPDX-License-Identifier: MIT
+-->
+
+```{include} ../../vllm.md
+```

docs/rocm-docs/getting-started.md

@@ -18,6 +18,10 @@ SPDX-License-Identifier: MIT
 :end-before: "Running the command when a"
 ```
 
+<!-- The prose below is a deliberate copy of the README sentence, with the
+     cross-reference retargeted to this site. The link text is then reused as
+     the `:start-after:` anchor for the next include, which also matches the
+     original sentence in README.md; edit both together. -->
 Running the command when a managed runtime is already the active default asks
 first, because the new install takes over as the active default; see
 [ROCm installation](commands.md#rocm-installation) for that gate and the flags
@@ -28,7 +32,7 @@ that approve it without a prompt.
 :end-before: "You can also serve any compatible Hugging Face model directly"
 ```
 
-You can also serve any compatible Hugging Face model directly — see
+You can also serve any compatible Hugging Face model directly. See
 [Model serving](commands.md#model-serving) for the GGUF-vs-safetensors rule,
 since which form works depends on the engine your GPU selects.
 

docs/rocm-docs/index.rst

@@ -26,18 +26,16 @@ The ROCm CLI public repository is located at
 .. grid:: 2
    :gutter: 3
 
-   .. grid-item-card:: Demos
-
-      * :doc:`See ROCm CLI in action <demos>`
-
    .. grid-item-card:: Install
 
       * :doc:`Installing ROCm CLI <install/installation>`
 
    .. grid-item-card:: Getting started
 
       * :doc:`Getting started with ROCm CLI <getting-started>`
+      * :doc:`See ROCm CLI in action <demos>`
 
-   .. grid-item-card:: Commands
+   .. grid-item-card:: Use ROCm CLI
 
       * :doc:`Command reference <commands>`
+      * :doc:`vLLM adapter <engines/vllm>`

docs/rocm-docs/install/installation.md

@@ -16,10 +16,18 @@ ROCm CLI ships as a single prebuilt binary. Platform support:
 Live dashboard telemetry requires Linux or WSL2 (see
 [Interactive interfaces](../getting-started.md#interactive-interfaces)). vLLM
 serving is Linux or WSL2 only (see
-[docs/vllm.md](https://github.com/ROCm/rocm-cli/blob/main/docs/vllm.md)).
+[vLLM adapter](../engines/vllm.md)).
+
+<!-- The prose below is a deliberate copy of the README sentence, with the
+     cross-reference retargeted to this site. The link text is then reused as
+     the `:start-after:` anchor for the next include, which also matches the
+     original sentence in README.md; edit both together. -->
+ROCm CLI supports multiple ROCm versions: 7.14, 10.0, and 10.1. ROCm 10.0 and
+later use a different install path; see
+[ROCm 10 and newer](../commands.md#rocm-10-and-newer).
 
 ```{include} ../../../README.md
-:start-after: "only (see [docs/vllm.md](docs/vllm.md))."
+:start-after: "[ROCm 10 and newer](#rocm-10-and-newer)."
 :end-before: "> [!IMPORTANT]"
 ```
 

docs/rocm-docs/sphinx/_toc.yml.in

@@ -1,18 +1,19 @@
 root: index
 subtrees:
-  - caption: Demos
-    entries:
-      - file: demos
-        title: See ROCm CLI in action
   - caption: Install
     entries:
       - file: install/installation
   - caption: Getting started
     entries:
       - file: getting-started
-  - caption: Commands
+      - file: demos
+        title: See ROCm CLI in action
+  - caption: Use ROCm CLI
     entries:
       - file: commands
+        title: Command reference
+      - file: engines/vllm
+        title: vLLM adapter
   - caption: About
     entries:
       - file: about/contributing