autodoc: Use type stub files when documenting native modules

[AA-Turner]

Purpose

This builds on work originally proposed by @alliefitter in #4824. Autodoc now attempts to load a .pyi stub file for any native modules being documented.

Currently this will become the default behaviour, but we could put it behind an environment variable if it might be disruptive (SPHINX_AUTODOC_USE_NATIVE_STUB_FILES?).

cc commenters from original threads: @JosXa, @hoefling, @Vanuan, @cmpute, @brenthuisman, @kdschlosser, @jonnor.

References

• Closes Added support for reading .pyi files. #4824
• Closes Use PEP 484 stub files when documenting native extensions with autodoc #7630
• https://github.com/bayashi-cl/stubdoc (Use PEP 484 stub files when documenting native extensions with autodoc #7630 (comment))

A