Sphinx Guidance?

[ax3l]

Hi,

Thank you so much for this project!

I was reading up a bit and cannot find yet guidance on this:
Which extensions do people use to read stub-only .pyi files into Sphinx docs, e.g., for quick RTD builds?

• autoapi.extension (sphinx-autoapi)?
• sphinx.ext.autodoc?
• m.css?

Are there a few example pybind11 projects you are aware of that build API docs purely from .pyi files?

My workflow is as follows:

• update .pyi stubs in CI, where I can run a long time (build pybind11 modules)
• commit .pyi stubs to the repo
• build on RTD for Sphinx docs (w/o long runtime that would be sufficient to build the pybind11 modules)

[sizmailov]

Hi!

As far as I know, none of the listed tools account for *.pyi files in the package.

m.css inspects binary modules, just like pybind11-stubgen does, so that you can get decent results out of the box.

You can make a "fake" module out of generated stubs by renaming all *.pyi files to *.py for doc generation purposes only. I can add --stub-extension= CLI option to make it easier for this use case.

[ax3l]

Thank you for the guidance, renaming is a great suggestion.

Yes on tooling support; I did some checks with sphinx-autoapi, which seems to pick up .pyi files but still eventually struggles when the main C extension is not found.

[virtuald]

What we do is build the wheels in github actions, publish the wheels as an artifact, and then tell RTD to retrieve the correct wheel and install it -- at which point sphinx can do the things it normally does. It requires setting up a token to access the github API, but works great.

• https://github.com/robotpy/robotpy-sphinx-plugin/blob/main/robotpy_sphinx/download_and_install.py
• .readthedocs.yml configuration: https://github.com/robotpy/pyntcore/blob/main/.readthedocs.yml#L12

[abhinavnatarajan]

I second @sizmailov's suggestion of renaming - in my own workflow I use the stub files for doc generation rather than the actual wheel because functions in a *.so file cannot be inspected, which means that some functionality of the sphinx autodoc extension does not work properly when using the actual package. I generate the stubs and rename them to *.py files in the CI workflow only for docs generation.

[ax3l]

Thank you all.
I'll close this now as solved.

My current workflow is: I run pybind11-stubgen on my mainline branches after merges to refresh .pyi files (link, link). During Sphinx builds (link), e.g., on RTD, where I want to avoid rebuilding the whole C++ part, I copy in and rename the .pyi files to .py and set the PYTHONPATH to pick them up. I also create a .zip archive for download, so that dependent Sphinx projects can download all the .pyi files in their builds (link).

I use .. autoclass:: and .. autofunction:: in Sphinx for select classes/functions (link).