From ecab3746cf4fe3f4f0e69e82cb4b5fc724053872 Mon Sep 17 00:00:00 2001 From: whn <142425816+Whning0513@users.noreply.github.com> Date: Thu, 22 Oct 2026 09:02:01 +0800 Subject: [PATCH] Document autodoc native module stubs environment variable (#14563) Co-authored-by: Jared Dillard --- doc/usage/extensions/autodoc.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 17445b1963..6c230ca56d 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -98,6 +98,24 @@ There are two ways to ensure this: the :confval:`autodoc_mock_imports` setting. +Using native modules instead of type stubs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Starting with Sphinx 9.1, autodoc may use a neighboring ``.pyi`` type stub +when importing a module. For native extension modules whose documentation is +available only on the runtime objects, set the +``SPHINX_AUTODOC_IGNORE_NATIVE_MODULE_TYPE_STUBS`` environment variable +to a non-empty value to make autodoc import the native module directly: + +.. code-block:: console + + $ SPHINX_AUTODOC_IGNORE_NATIVE_MODULE_TYPE_STUBS=1 sphinx-build ... + +On Windows, set the variable in the shell before running +the :program:`sphinx-build` command. + +.. versionadded:: 9.1 + Usage ^^^^^