You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Property docstrings are no longer handled correctly in version 1.0 and above, for the following reasons:
The method ExtractSignaturesFromPybind11Docstrings.handle_property defined in pybind11_stubgen.parser.mixins.parse does not populate the doc attribute of the Property object that is returned. Property objects defined by pybind11 attach the docstring to the property object and a signature to the fget method, and the output stubs from pybind11-stubgen only contain the latter.
Printer.print_property from pybind11_stubgen.printer does not insert the property docstring into the result.
The class 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 that ReplaceReadWritePropertyWithField 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.
The text was updated successfully, but these errors were encountered:
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.
The text was updated successfully, but these errors were encountered: