Repository navigation
docs: setup ROCm docs toolchain and publishing - #1632
Conversation
🏷️ CI GuideRuns automatically on every eligible PR before approval:
Heavy model tests:
|
|
Thanks for the migration. The overall direction is sound — every file referenced by 1. 2. 3. Stale root-level Sphinx HTML persists on gh-pages after the migration, so deep links keep serving outdated docs. 4. 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). |
There was a problem hiding this comment.
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_pathpoints at./sphinx/_toc.yml, but the repo only containsdocs/sphinx/_toc.yml.in(and_toc.ymlis gitignored). With the currentdocs/Makefileinvokingsphinx-builddirectly 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.ymlfrom the.inat config-load time (or pointexternal_toc_pathdirectly at the checked-in.infile).
external_toc_path = "./sphinx/_toc.yml"
docs/conf.py:58
myst_enable_extensionsis set using{ ... }, which creates a Pythonset. 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",
}
There was a problem hiding this comment.
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
copyrightcontains a%Yplaceholder, but Sphinx doesn’t expandstrftimetokens in this field by default, so%Ywill likely render verbatim in the HTML footer.
copyright = "Copyright (c) %Y Advanced Micro Devices, Inc. All rights reserved."
docs/conf.py:25
external_toc_pathpoints to./sphinx/_toc.yml, but the repo only checks indocs/sphinx/_toc.yml.in(and.gitignoreignores_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_extensionsis 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/"
chore: regenerate requirements.txt
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
ca8bb66 to
2114b0e
Compare
There was a problem hiding this comment.
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_pathpoints to./sphinx/_toc.yml, but the repository only containsdocs/sphinx/_toc.yml.inand there is no checked-in build step (docs/Makefile or .readthedocs.yaml) that generates_toc.ymlbefore Sphinx starts. This will make builds fail whensphinx-external-toc(likely enabled viarocm_docs) tries to read the file.
external_toc_path = "./sphinx/_toc.yml"
docs/conf.py:60
myst_enable_extensionsis currently assigned with{ ... }, which creates a Pythonset. 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.mdexists 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
For (1.), 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.
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 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). |
There was a problem hiding this comment.
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_pathpoints to./sphinx/_toc.yml, but this PR only addsdocs/sphinx/_toc.yml.inanddocs/.gitignoreignoressphinx/_toc.yml. With no generation step indocs/Makefileor.readthedocs.yaml, docs builds can fail due to a missing external ToC file. Pointexternal_toc_pathat the checked-in ToC source (or add an explicit generation step).
external_toc_path = "./sphinx/_toc.yml"
docs/conf.py:10
copyrightcontains a literal%Y, which Sphinx treats as plain text (it does not applystrftimeformatting). This will likely render%Yverbatim 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."
| <!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/"> |

Motivation
Update Sphinx theme and add Read the Docs configs for publication.
Remove old GitHub pages workflow. The new publishing location is https://rocm.docs.amd.com/projects/atom/en/latest/ and is managed by Read the Docs.
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.inTest Plan
Test Result
Submission Checklist