Closed abhinavnatarajan closed 1 year ago
Thanks for the detailed report.
Could you check that #118 works as expected?
pip install git+https://github.com/sizmailov/pybind11-stubgen.git@fix-missing-property-docstrings
@abhinavnatarajan I went ahead and merged the fix. Feel free to reopen/create new one.
That seems to have fixed the issue. Many thanks for your great work on this package!
Property docstrings are no longer handled correctly in version 1.0 and above, for the following reasons:
ExtractSignaturesFromPybind11Docstrings.handle_property
defined inpybind11_stubgen.parser.mixins.parse
does not populate thedoc
attribute of theProperty
object that is returned. Property objects defined by pybind11 attach the docstring to the property object and a signature to thefget
method, and the output stubs from pybind11-stubgen only contain the latter.Printer.print_property
frompybind11_stubgen.printer
does not insert the property docstring into the result.ReplaceReadWritePropertyWithField
replaces class properties with class attributes, but attributes and properties are fundamentally different. Properties can have docstrings, while attributes cannot. Moreover, documentation generators like the autodoc extension in Sphinx treat properties and attributes differently. The upshot is thatReplaceReadWritePropertyWithField
causes any docstrings written for a property to get removed, and for that property to be documented as an attribute.Context: I'm using pybind11-stubgen to generate stubs and docstrings for my pybind11 project, which I then use in Sphinx to autogenerate documentation. This works better than using Sphinx directly on the extension module generated by pybind11 because the code generated by pybind11 cannot be inspected for PEP 484 style annotations, which breaks some functionality of sphinx.ext.autodoc.