[doc] Don't mock installed numpy/pyarrow in autodoc_mock_imports#64457
Merged
richardliaw merged 1 commit intoJul 1, 2026
Merged
Conversation
numpy and pyarrow (and pyarrow.compute) are installed in the docs build environment (doc/requirements-doc.lock.txt); pyarrow is a direct requirements-doc entry and numpy is foundational to that stack. Mocking a library that is actually installed shadows the real module: an eager import in a documented class body hits the mock and aborts the whole package import, surfacing as a misleading decoy error (the read_lerobot class, ray-project#63821). Remove these three entries so autodoc introspects the real, installed modules. Add a comment recording the mock-iff-absent policy so they aren't re-added. tensorflow is also installed (a direct requirements-doc entry) but is left mocked on purpose: importing it for real breaks the autodoc import of ray.rllib.algorithms.algorithm at build time. Libraries genuinely absent from the docs lock stay mocked. Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates doc/source/conf.py to remove numpy, pyarrow, and pyarrow.compute from the autodoc_mock_imports list. This prevents mocking libraries that are already installed in the documentation build environment, which can shadow real modules and cause misleading import errors. A detailed explanatory comment has also been added. There are no review comments, so I have no feedback to provide.
ray-gardener
Bot
added
docs
ArturNiederfahrenhorst
approved these changes
Jul 1, 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
4 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.
Why
autodoc_mock_importsindoc/source/conf.pymocksnumpyandpyarrow, but both are installed in the docs build environment (doc/requirements-doc.lock.txt;pyarrowis a directrequirements-doc.txtentry andnumpyis foundational to the installed stack).Mocking a library that's actually installed shadows the real module. An eager import in a documented class body then hits the mock instead of the real library and aborts the whole package import, surfacing as a misleading decoy error. This is the failure class fixed in #63821 (the
read_lerobotbreak), where a mocked-but-needed library broke an unrelated import.What
Remove
numpy,pyarrow, andpyarrow.computefromautodoc_mock_importsso autodoc introspects the real, installed modules. Libraries genuinely absent from the docs lock stay mocked. A comment records the mock-iff-absent policy so the entries aren't re-added.tensorflowis also installed (a directrequirements-docentry) but is intentionally left mocked: importing it for real breaks the autodoc import ofray.rllib.algorithms.algorithmat build time. The comment notes this.Checks
Built the full docs in a faithful Linux environment: the pinned
python/deplocks/docs/docbuild_depset_py3.11.lockinstalled in a container, run with the samepython -m sphinx ... -Wcommand (warnings as errors) the RtD config uses. The build completes green —build succeeded.with zero Sphinx warnings; removing the three entries introduces none.