stubgen should also include docstrings
#11965
Comments
|
I think that it should be an option 🤔 I can imagine many users do not want that as well. But, as a configurable feature - why not? Are you interested in working on this? 🙂 |
|
For what it's worth, sizmailov/pybind11-stubgen already supports extracting docstrings from C modules and including them in the stub files. I think this would be most useful for external C or C++ modules, because some IDEs don't look for signatures or docstrings in compiled modules. For example, Pylance in VSCode doesn't show documentation for functions in compiled modules, even with stub files generated by |
|
Subscribing and +1 on |
This MR allows python classes created in C++ to show up in IDEs and work with linters. It works by using pybind11-stubgen to create .pyi files that are then included in the package. The result is this:  Only downside is the pybind11-stubgen isnt too actively maintained (but its also not complex). And the option for generating the output location is limited. So in our output we get: ``` common/ __init__.pyi cudf_helpers/ __init__.pyi messages/ __init__.pyi stages/ __init__.pyi common.so cudf_helpers.so messages.so stages.so ``` It would be better to be organized like the following: ``` common.pyi common.so cudf_helpers.pyi cudf_helpers.so messages.pyi messages.so stages.pyi stages.so ``` The only alternative is to use mypy. However, they dont support docstrings according to this issue: python/mypy#11965 Closes #99 Authors: - Michael Demoret (https://github.com/mdemoret-nv) Approvers: - David Gardner (https://github.com/dagardner-nv) - Devin Robison (https://github.com/drobison00) - Bartley Richardson (https://github.com/BartleyR) URL: #100
|
Starting point would be: https://github.com/python/mypy/blob/master/mypy/stubgen.py |
Add a --include-docstrings flag to stubgen This was suggested in python#11965. When using this flag, the .pyi files will include docstrings for Python classes and functions and for C extension functions.
### Description Closes #11965. Add a --include-docstrings flag to stubgen. This was suggested in #11965 along with a use case. When using this flag, the .pyi files will include docstrings for Python classes and functions and for C extension functions. The flag is optional and does not change the default stubgen behaviour. When using the flag, the resulting function stubs that contain docstring will no longer be one-liners, but functions without a docstring still retain the default one-liner style. Example input: ```python class A: """class docstring""" def func(): """func docstring""" ... def nodoc(): ... ``` output: ```python class A: """class docstring""" def func() -> None: """func docstring""" ... def nodoc() -> None: ... ``` ## Test Plan Tests `testIncludeDocstrings` and `testIgnoreDocstrings` were added to `test-data/unit/stubgen.test` to ensure the code works as intended. All other tests passed as well. C extension docstrings are tested using an updated bash script `misc/test_stubgenc.sh` with test data in `test-data/pybind11_mypy_demo/stubgen-include-docs` in same fashion as in an already existing test. --------- Co-authored-by: Shantanu <[email protected]>
|
Thanks for making this happen @chylek and @ilevkivskyi! 🎉 |
Feature
When generating
*.pyifiles, docstrings describing the contained classes, methods and members are not included in the file.Pitch
In my opinion it would be helpful to have them and other tools for
pyigeneration do exactly this.The text was updated successfully, but these errors were encountered: