Open ax3l opened 11 months ago
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.
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.
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.
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.
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)?Are there a few example pybind11 projects you are aware of that build API docs purely from
.pyi
files?My workflow is as follows:
.pyi
stubs in CI, where I can run a long time (build pybind11 modules).pyi
stubs to the repo