autodoc: Use type stub files when documenting native modules (#13253)

tests/test_extensions/test_ext_autodoc_importer.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from sphinx.ext.autodoc.importer import import_module
+
+
+def test_import_native_module_stubs(rootdir: Path) -> None:
+    fish_licence_root = rootdir / 'test-ext-apidoc-duplicates'
+
+    sys_path = list(sys.path)
+    sys.path.insert(0, str(fish_licence_root))
+    halibut = import_module('fish_licence.halibut')
+    sys.path[:] = sys_path
+
+    assert halibut.__file__.endswith('halibut.pyi')
+    assert halibut.__spec__.origin.endswith('halibut.pyi')
+
+    halibut_path = Path(halibut.__file__).resolve()
+    assert halibut_path.is_file()
+    assert halibut_path == fish_licence_root / 'fish_licence' / 'halibut.pyi'