[BUG]: stubgen issues/improvement suggestions

[oscargus]

Problem description

Two issues found in the otherwise very nice and useable stub generator.

1. Things starting with _ are dropped. Consider an __init__.py looking like (_foo is a nanobind extension):

from _foo import bar, _bar
from _version import __version__

__all__ = ["bar", "_bar", "__version__"]

This will generate a stub file __init__.pyi like:

from _foo import bar as bar

__all__ = ["bar", "_bar", "__version__"]

which then e.g. ruff will complain about since _bar and __version__ are seemingly not imported.

(Maybe the idea is to only generate stubfiles for _foo, but I imagine that there may be cases where this is still useful.)

(There is also the thing that generating stub files for _foo (extension) will be foo.pyi, but that can be worked around and I understand why that is done.)

2. Trailing empty lines are dropped from doc-strings. While this is often removed by formatters, it causes problems when using doctest examples as the """ are interpreted by doctest to be included in the expected result. Not sure if this is a result of the stubs or the parsing of doc-strings though...

Reproducible example code

No response

[oscargus]

After reading the help-text (someone else set up a script to generate the stubs in my project) I realize that _bar can be included by the -P switch, but __version__ is still failing. Using __version__ seems to be a rather common approach?

The doc-string issue still remains (and is the only way I see to actually run doctest on extensions?)

[wjakob]

The stripping of newlines is likely intentional (it's been a while since I wrote this code—I think I needed it to deal with some auto-extracted C++ docstrings that were mapped onto Python). As you noticed, there is a flag to include private bits. For the __version__, I am not sure. Feel free to create a PR if this seriously bothers you, but for now I will close this as won't fix / out of scope.