Skip to content

docs: fix broken README model links breaking docs build - #4468

Merged
ko3n1g merged 1 commit into
mainfrom
ko3n1g/docs/fix-readme-xref
Jun 23, 2026
Merged

ko3n1g merged 1 commit into
mainfrom
ko3n1g/docs/fix-readme-xref

Conversation

@ko3n1g

@ko3n1g ko3n1g commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Background

The release / finalize / build-docs job fails the Sphinx build with --fail-on-warning:

README.md:220: WARNING: 'myst' cross-reference target not found: 'src/megatron/bridge/diffusion/models' [myst.xref_missing]
README.md:221: WARNING: 'myst' cross-reference target not found: 'src/megatron/bridge/models/ernie' [myst.xref_missing]
README.md:221: WARNING: 'myst' cross-reference target not found: 'src/megatron/bridge/models/ernie_vl' [myst.xref_missing]
build finished with problems, 3 warnings (with warnings treated as errors).

docs/index.md pulls the root README in via {include} ../README.md, so MyST resolves the README's relative links as cross-references. The three Diffusion/Ernie rows in the Supported Models table linked to bare source directories, which have no doc target and fail resolution.

What changed

  • Convert the Diffusion / Ernie / Ernie-VL source-directory links to full GitHub URLs.

Details

  • The repo already uses full https://github.com/NVIDIA-NeMo/Megatron-Bridge/tree/main/... URLs for every other source-code reference in the README (e.g. model bridges, PEFT, recipes); rows backed by a doc page keep their docs/models/<family>/index.md link. This change just makes the three offending rows follow the same convention.
  • External URLs are not treated as MyST cross-references, so the --fail-on-warning build passes.
  • Verified no other bare relative source/example/script links remain in the README.

The Sphinx docs build includes the root README via {include} and treats
relative links as MyST cross-references. The bare source-directory links
for Diffusion/Ernie/Ernie-VL had no resolvable doc target, failing the
--fail-on-warning build. Convert them to full GitHub URLs, matching the
convention already used for other source-code links in the README.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: oliver könig <okoenig@nvidia.com>
@ko3n1g ko3n1g added docs Documentation-only updates or documentation debt docs-only With great power comes great responsibility. labels Jun 23, 2026
@claude

claude Bot commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

LGTM — the three relative source-directory links are correctly converted to full GitHub URLs, matching the convention already used for every other source-code reference in the README (e.g. line 213). Target directories all exist on main.

Suggested test cases

No perf tests impacted. This is a docs-only change. The relevant validation is the Sphinx --fail-on-warning build in the release / finalize / build-docs CI job.

@ko3n1g
ko3n1g merged commit d26b3f9 into main Jun 23, 2026
39 checks passed
@ko3n1g
ko3n1g deleted the ko3n1g/docs/fix-readme-xref branch June 23, 2026 16:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation-only updates or documentation debt docs-only With great power comes great responsibility.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants