sphinx-doc / sphinx-doc/sphinx
Autodoc: Document `SPHINX_AUTODOC_IGNORE_NATIVE_MODULE_TYPE_STUBS` variable added in v9.1.0
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Is your feature request related to a problem? Please describe.
Yes. Following the release of Sphinx 9.1.0, autodoc attempts to use neighboring .pyi type stubs via _StubFileLoader instead of importing native binary modules (like Cython extensions). As discussed in #13415, this breaks docstring extraction for compiled cdef class objects, triggering silent AttributeError warnings during safe_getattr lookups.
While PR #13446 successfully implemented the SPHINX_AUTODOC_IGNORE_NATIVE_MODULE_TYPE_STUBS environment variable to bypass this issue, the variable is completely undocumented. Upgrading users face completely blank or broken API reference pages with no guidance in the documentation on how to restore native runtime execution.
Describe the solution you'd like
Please explicitly document the SPHINX_AUTODOC_IGNORE_NATIVE_MODULE_TYPE_STUBS environment variable within the Autodoc configuration or invocation guides so compiled extension authors know how to safely opt out.
Describe alternatives you've considered
We attempted various conf.py monkeypatches and to override safe_getattr or type-checking routines.
Finally through overriding Documenter.get_attr and inspecting a module's __spec__ and __file__ attributes was it apparent that the modules were being loaded by sphinx.ext.autodoc._dynamic._importer._StubFileLoader, leading to a trail of breadcrumbs which finally lead to the discovery of:
https://github.com/sphinx-doc/sphinx/blob/c1b618c559e6de70e5198ed6876f5b9fab88face/sphinx/ext/autodoc/_dynamic/_importer.py#L208-L221
The environment variable added in #13446 is the correct and intended fix; it simply needs to be discoverable in the official documentation.
Additional context
The real-world impact of this missing documentation is captured across consecutive Read the Docs builds in this PR: https://github.com/cyndilib/cyndilib/pull/114
- First Build (Broken): Upgrading to
Sphinx >= 9.1completely wiped out the API reference pages due to silent stub resolution failures. - Second Build (Fixed): Manually passing
SPHINX_AUTODOC_IGNORE_NATIVE_MODULE_TYPE_STUBS=1instantly restored full binary docstring parsing.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Autodoc configuration or invocation guides and review the existing implementation in sphinx/ext/autodoc/_dynamic/_importer.py, especially lines 208–221. Document SPHINX_AUTODOC_IGNORE_NATIVE_MODULE_TYPE_STUBS, including when compiled extensions may need it and how to set it; done means users can discover and apply the workaround from the official documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100