Fix build abort on broken autodoc reference blocking link resolution - #814
Open
aether-png wants to merge 1 commit into
Open
Fix build abort on broken autodoc reference blocking link resolution#814aether-png wants to merge 1 commit into
aether-png wants to merge 1 commit into
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #475
Root cause
build_mdx_files() aborted the entire build immediately on the first file with a broken [[autodoc]] reference. This happened before resolve_links() ran, so every [~Class.method]-style reference across the whole doc set was left unresolved when any single reference broke — including the trailing-underscore case in #475, where the unresolved raw text got picked up by markdown's emphasis parsing.
A second issue surfaced once the abort was removed: check_toc_integrity(), called right after, independently failed because the file that errored was legitimately absent from the output directory (never written) but still listed in _toctree.yml.
Fix
build_mdx_files() now collects per-file errors and continues instead of raising immediately
check_toc_integrity() accepts a set of known-failed files and skips them when checking for missing output
build_doc() now lets resolve_links, notebook building, and toctree renaming run regardless of MDX errors, and raises the deployment-failure error only at the very end
Testing
Reproduced the original bug: single broken [[autodoc]] reference → full build abort → every reference left unresolved
Verified fix: same broken reference → build completes, clip_grad_value_ (and all other references) resolve correctly, error is raised only at the end
Verified multi-error case: two broken references in different files → both correctly reported together, neither dropped
Verified clean build (no broken references) has zero regressions
Ran full existing test suite; confirmed the 3 pre-existing failures (GlmAsrForConditionalGeneration import error, a cascading AutoProcessor NameError, and a Windows-specific [WinError 2] subprocess issue in test_format_code_example) are present identically on unmodified main, unrelated to this change