sphinx-doc / sphinx-doc/sphinx

Autodoc: Document `SPHINX_AUTODOC_IGNORE_NATIVE_MODULE_TYPE_STUBS` variable added in v9.1.0

Open Beginner friendly
#14,528 0 comments 0 reactions 0 assignees View on GitHub

@Whning0513 is already working on this.

Since Jul 30, 2026.

  • #14563 by @Whning0513 — open
extensions:autodoc type:proposal
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.1 completely wiped out the API reference pages due to silent stub resolution failures.
  • Second Build (Fixed): Manually passing SPHINX_AUTODOC_IGNORE_NATIVE_MODULE_TYPE_STUBS=1 instantly restored full binary docstring parsing.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.