search

sizmailov / pybind11-stubgen

Generate stubs for python modules
Other
228 stars 45 forks source link

Sphinx Guidance? #141

Open ax3l opened 11 months ago

ax3l commented 11 months ago

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?

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

My workflow is as follows:

sizmailov commented 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.

ax3l commented 11 months ago

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 commented 10 months ago

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.

abhinavnatarajan commented 10 months ago

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.