Skip to content

docs: setup ROCm docs toolchain and publishing - #1632

Merged
valarLip merged 19 commits into
mainfrom
docs/setup-rtd
Jul 21, 2026
Merged

valarLip merged 19 commits into
mainfrom
docs/setup-rtd

Conversation

@peterjunpark

@peterjunpark peterjunpark commented Jul 17, 2026 •

Copy link
Copy Markdown
Contributor

Motivation

These changes bring ATOM docs in line with other ROCm docs.

The following dashboards remain deployed on GitHub pages and should be unaffected for now.

Technical Details

Note: the left side nav is now managed by docs/sphinx/_toc.yml.in

Test Plan

Test Result

Submission Checklist

Copilot AI review requested due to automatic review settings July 17, 2026 15:24
@github-actions

Copy link
Copy Markdown
Contributor

🏷️ CI Guide

Runs automatically on every eligible PR before approval:

  • ✅ Pre Checkin: Black, Ruff, catalog schema validation, non-GPU unit tests

Heavy model tests:

  • ✅ Run after the PR is approved and Pre Checkin passes
  • ✅ Run immediately when an approval review is submitted
  • ✅ Can be requested before approval with labels
Label Tests
ci:full Run all heavy PR model tests: native ATOM, vLLM, and SGLang
ci:atom Run native ATOM model accuracy tests
ci:vllm Run ATOM vLLM OOT model accuracy tests
ci:sglang Run ATOM SGLang model accuracy tests

Heavy jobs are skipped when the PR is not approved and no matching ci:* label is present.
Add labels via the sidebar or gh pr edit 1632 --add-label <label>

This comment was marked as duplicate.

Copilot AI review requested due to automatic review settings July 17, 2026 15:30

This comment was marked as duplicate.

Copilot AI review requested due to automatic review settings July 17, 2026 15:34

This comment was marked as duplicate.

Copilot AI review requested due to automatic review settings July 17, 2026 15:39

This comment was marked as duplicate.

Copilot AI review requested due to automatic review settings July 17, 2026 15:51

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

Comment thread docs/conf.py Resolved
Copilot AI review requested due to automatic review settings July 17, 2026 16:44

This comment was marked as duplicate.

Copilot AI review requested due to automatic review settings July 17, 2026 17:42

This comment was marked as duplicate.

@valarLip

Copy link
Copy Markdown
Collaborator

Thanks for the migration. The overall direction is sound — every file referenced by _toc.yml.in exists, the link rewrites are correct, and the #35→#36 anchor change is a genuine fix (the heading really is ### 3.6 Plugin mode). A few things worth addressing, in priority order.

1. .github/pages/docs/index.html and .github/pages/index.html are byte-for-byte identical. The redirect target lives in two separate copies with no shared source. Any future change to the destination URL, canonical link, or wording has to be made in both places, and the two will silently drift the moment someone edits only one — leaving one of the two entry points (/ or /docs/) pointing somewhere different from the other. Please collapse this to a single source (generate both from one template at deploy time, or copy in the workflow) so the redirect is defined exactly once.

2. .github/workflows/docs.yml (deleted) removes the only PR-time docs build validation. The deleted workflow had a pull_request trigger running make html, which caught conf.py / _toc.yml / rst build errors before merge. With it gone, this repo's CI no longer validates the docs build; RTD only builds post-merge (or via RTD's PR integration, if configured) — which is exactly the gate you want during a large toolchain migration like this. Also, if branch protection still lists the old build-docs job as a required check, open PRs may block on a check that will never run again. Could you confirm the RTD PR-preview build is enabled as a replacement gate, and check branch protection for a stale build-docs required check?

3. Stale root-level Sphinx HTML persists on gh-pages after the migration, so deep links keep serving outdated docs. deploy-pages.yml only overwrites the root index.html and git rm -rs the docs/ and dissecting_dsv4_compressor/ subdirs, but the gh-pages root currently holds a full old Sphinx site (architecture_guide.html, configuration_guide.html, environment_variables.html, … plus _static/, _sources/, api/, search.html, searchindex.js, objects.inv) — none of those root-level per-page files are removed. So rocm.github.io/ATOM/ and /docs/ redirect, but deep links like rocm.github.io/ATOM/architecture_guide.html (bookmarks, search-engine results) will serve outdated content indefinitely. Please add a cleanup step that removes the stale root-level files (or git rm them from gh-pages) so the migration is complete.

4. docs/conf.py — myst_enable_extensions changed from a list to a set ([...] → {...}). MyST expects an ordered sequence; a set is unordered and unconventional. It works today (it's iterable) but reads as an accidental slip from this edit (the same block also comments out myst_parser). Please revert it to a list.

No build-breaking or inference-affecting issues surfaced — the risks are concentrated in the duplicated redirect source and the incomplete migration (lost build validation + uncleaned gh-pages files).

@zufayu
zufayu requested a review from gyohuangxin July 20, 2026 01:26
Copilot AI review requested due to automatic review settings July 20, 2026 18:11

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

docs/conf.py:25

  • external_toc_path points at ./sphinx/_toc.yml, but the repo only contains docs/sphinx/_toc.yml.in (and _toc.yml is gitignored). With the current docs/Makefile invoking sphinx-build directly and no pre-step to materialize _toc.yml, local builds (and any RTD build that doesn’t run an external generation hook) will fail with a missing ToC file. Consider generating _toc.yml from the .in at config-load time (or point external_toc_path directly at the checked-in .in file).
external_toc_path = "./sphinx/_toc.yml"

docs/conf.py:58

  • myst_enable_extensions is set using { ... }, which creates a Python set. MyST expects a list/tuple of extension names; using a set can lead to unstable ordering and may not be accepted by the config validator depending on MyST/Sphinx versions.
myst_enable_extensions = {
    "colon_fence",
    "deflist",
}

Comment thread .github/workflows/deploy-pages.yml Resolved
Copilot AI review requested due to automatic review settings July 20, 2026 18:16

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (4)

docs/conf.py:10

  • copyright contains a %Y placeholder, but Sphinx doesn’t expand strftime tokens in this field by default, so %Y will likely render verbatim in the HTML footer.
copyright = "Copyright (c) %Y Advanced Micro Devices, Inc. All rights reserved."

docs/conf.py:25

  • external_toc_path points to ./sphinx/_toc.yml, but the repo only checks in docs/sphinx/_toc.yml.in (and .gitignore ignores _toc.yml). There’s no build step in this repo (Makefile or .readthedocs.yaml) that generates _toc.yml, so Read the Docs/local Sphinx builds can fail with a missing ToC file.
external_toc_path = "./sphinx/_toc.yml"

docs/conf.py:58

  • myst_enable_extensions is set using a Python set literal ({...}) rather than the list/tuple format MyST documents. Using a set can lead to unstable ordering and may break if the config validator expects a sequence type.
myst_enable_extensions = {
    "colon_fence",
    "deflist",
}

.github/workflows/deploy-pages.yml:49

  • cp -r "$dir"* won’t copy dotfiles and will error out if a page directory is ever empty (globbing produces a literal *), which would fail the deployment job. Copy the directory contents via /. to handle empty dirs and dotfiles safely.
          for dir in /tmp/pages_copy/*/; do
            page_name=$(basename "$dir")
            git rm -r --quiet "$page_name" 2>/dev/null || true
            mkdir -p "$page_name"
            cp -r "$dir"* "$page_name/"
            git add "$page_name/"

Comment thread README.md Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

docs/conf.py:26

  • external_toc_path points to ./sphinx/_toc.yml, but the repository only contains docs/sphinx/_toc.yml.in and there is no checked-in build step (docs/Makefile or .readthedocs.yaml) that generates _toc.yml before Sphinx starts. This will make builds fail when sphinx-external-toc (likely enabled via rocm_docs) tries to read the file.
external_toc_path = "./sphinx/_toc.yml"

docs/conf.py:60

  • myst_enable_extensions is currently assigned with { ... }, which creates a Python set. MyST expects a list/tuple of extension names; using a set can cause config validation errors (or at least nondeterministic ordering).
myst_enable_extensions = {
    "colon_fence",
    "deflist",
}

docs/sphinx/_toc.yml.in:36

  • docs/context_parallel_guide.md exists but is not referenced anywhere in the new external ToC, so it will be orphaned (not reachable from the left nav and may not be built, depending on Sphinx settings). Add it to the Reference section (or another appropriate section) so it remains discoverable.
      - file: scheduling_kv_cache_guide
        title: Scheduling and KV cache
      - file: distributed_guide
        title: Distributed cache
      - file: compilation_cudagraph_guide

@peterjunpark

peterjunpark commented Jul 21, 2026 •

Copy link
Copy Markdown
Contributor Author

Thanks for the migration. The overall direction is sound — every file referenced by _toc.yml.in exists, the link rewrites are correct, and the #35→#36 anchor change is a genuine fix (the heading really is ### 3.6 Plugin mode). A few things worth addressing, in priority order.

1. .github/pages/docs/index.html and .github/pages/index.html are byte-for-byte identical. The redirect target lives in two separate copies with no shared source. Any future change to the destination URL, canonical link, or wording has to be made in both places, and the two will silently drift the moment someone edits only one — leaving one of the two entry points (/ or /docs/) pointing somewhere different from the other. Please collapse this to a single source (generate both from one template at deploy time, or copy in the workflow) so the redirect is defined exactly once.

2. .github/workflows/docs.yml (deleted) removes the only PR-time docs build validation. The deleted workflow had a pull_request trigger running make html, which caught conf.py / _toc.yml / rst build errors before merge. With it gone, this repo's CI no longer validates the docs build; RTD only builds post-merge (or via RTD's PR integration, if configured) — which is exactly the gate you want during a large toolchain migration like this. Also, if branch protection still lists the old build-docs job as a required check, open PRs may block on a check that will never run again. Could you confirm the RTD PR-preview build is enabled as a replacement gate, and check branch protection for a stale build-docs required check?

3. Stale root-level Sphinx HTML persists on gh-pages after the migration, so deep links keep serving outdated docs. deploy-pages.yml only overwrites the root index.html and git rm -rs the docs/ and dissecting_dsv4_compressor/ subdirs, but the gh-pages root currently holds a full old Sphinx site (architecture_guide.html, configuration_guide.html, environment_variables.html, … plus _static/, _sources/, api/, search.html, searchindex.js, objects.inv) — none of those root-level per-page files are removed. So rocm.github.io/ATOM/ and /docs/ redirect, but deep links like rocm.github.io/ATOM/architecture_guide.html (bookmarks, search-engine results) will serve outdated content indefinitely. Please add a cleanup step that removes the stale root-level files (or git rm them from gh-pages) so the migration is complete.

4. docs/conf.py — myst_enable_extensions changed from a list to a set ([...] → {...}). MyST expects an ordered sequence; a set is unordered and unconventional. It works today (it's iterable) but reads as an accidental slip from this edit (the same block also comments out myst_parser). Please revert it to a list.

No build-breaking or inference-affecting issues surfaced — the risks are concentrated in the duplicated redirect source and the incomplete migration (lost build validation + uncleaned gh-pages files).

For (1.), .github/pages/docs/index.html has been deleted from this branch. Rather than generating docs/index.html from a workflow, the redirect is committed directly to gh-pages in a companion PR — defined once, no workflow machinery
needed. The deploy-pages.yml workflow no longer manages docs/. Please review #1656 to replace existing files with redirects.

For (2.), RTD PR integration is enabled and serves as the replacement gate. The old build-docs required check should be removed from branch protection.

image

For (3.), handled in a separate direct commit to gh-pages: all 22 stale Sphinx HTML pages under docs/ have been replaced with redirect stubs pointing to their RTD equivalents, and _sources/, _static/, and other build artifacts have
been removed. Please review #1656 to replace existing files with redirects.

For (4.), the set is intentional — reverting to a list triggers this build error:

  sphinx.errors.ExtensionError: Handler <bound method _DefaultSettings.update_config of
  <class 'rocm_docs.core._DefaultSettings'>> for event 'config-inited' threw an exception
  (exception: 'list' object has no attribute 'update')

rocm-docs-core calls .update() directly on whatever Sphinx stores for myst_enable_extensions (https://github.com/ROCm/rocm-docs-core/blob/6b032c090ba0b855abbdbc3fd33f15dc24ea769e/src/rocm_docs/core.py#L50).

Copilot AI review requested due to automatic review settings July 21, 2026 15:14

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 14 out of 15 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

docs/conf.py:26

  • external_toc_path points to ./sphinx/_toc.yml, but this PR only adds docs/sphinx/_toc.yml.in and docs/.gitignore ignores sphinx/_toc.yml. With no generation step in docs/Makefile or .readthedocs.yaml, docs builds can fail due to a missing external ToC file. Point external_toc_path at the checked-in ToC source (or add an explicit generation step).
external_toc_path = "./sphinx/_toc.yml"

docs/conf.py:10

  • copyright contains a literal %Y, which Sphinx treats as plain text (it does not apply strftime formatting). This will likely render %Y verbatim in the docs footer. Compute the year in Python (or hardcode the year range) so the output is correct.
copyright = "Copyright (c) %Y Advanced Micro Devices, Inc. All rights reserved."

Comment thread .github/pages/index.html
Comment on lines +1 to +5
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="refresh" content="0; url=https://rocm.docs.amd.com/projects/atom/en/latest/">
@valarLip
valarLip merged commit 14f4d38 into main Jul 21, 2026
21 of 23 checks passed
@valarLip
valarLip deleted the docs/setup-rtd branch July 21, 2026 15:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants