Skip to content

Fix build abort on broken autodoc reference blocking link resolution - #814

Open
aether-png wants to merge 1 commit into
huggingface:mainfrom
aether-png:fix-autodoc-error-abort-blocks-link-resolution
Open

Fix build abort on broken autodoc reference blocking link resolution#814
aether-png wants to merge 1 commit into
huggingface:mainfrom
aether-png:fix-autodoc-error-abort-blocks-link-resolution

Conversation

@aether-png

Copy link
Copy Markdown

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

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.

Underscore in certain function, is rendered as italic

1 participant