fix(sphinxdocs): materialize source symlinks to resolve relative cross-references (#3977) - #4005
Open
rickeylev wants to merge 13 commits into
Open
fix(sphinxdocs): materialize source symlinks to resolve relative cross-references (#3977)#4005rickeylev wants to merge 13 commits into
rickeylev wants to merge 13 commits into
Conversation
…refs and binary assets (bazel-contrib#3977)
…e directory
Sphinx/MyST relative cross-reference resolution fails when input files are symlinks because os.path.realpath() resolves outside the source directory.
Add ConcurrentCopyTree in sphinx_build.py to recursively copy the source tree into a work-private '{srcdir}.worker-in.d' directory concurrently using a ThreadPoolExecutor before invoking Sphinx.
…ialization Sphinx/MyST relative cross-reference resolution fails when input files are symlinks because os.path.realpath() resolves outside the source directory. Add multi-threaded DirectorySyncer in sphinx_build.py supporting SHA-aware incremental sync(entries) and non-worker copytree(), forcing copied files to be user-writable and collecting errors into DirectorySyncerError. Add comprehensive unit test suite in tests/sphinx_build/.
…_create_executor helper Improve DirectorySyncer in sphinx_build.py by using pathlib.Path objects directly, replacing numeric permission literals with stat module constants, making copied files user-writable via stat.S_IWUSR, and factoring ThreadPoolExecutor creation into a _create_executor context manager.
aignas
approved these changes
Aug 5, 2026
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
2 participants
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.
In Sphinx with MyST, relative cross-references (
myst.xref_missing)break when resolving relative paths across symlinked source files inside
Bazel's
_sourcesdirectory because Bazel symlinks resolve canonicalpaths that escape the source tree.
To fix this, replaced input symlinking in
_relocatewith physical filematerialization in
sphinx_build.py. ImplementedDirectorySyncertoconcurrently synchronize files into a work-private
{srcdir}.worker-in.ddirectory using SHA-based change detection forworker requests and full recursive copying for non-worker requests.
Fixes #3977