stubgen: combine --include-docstrings and typeshed

[mikez]

Feature

Run stubgen --include-docstrings -p $STDLIB_PACKAGE --typeshed (?) or some other way and have it generate a stub that has the same syntax as the typeshed with docstrings included.

Pitch

Right now, stubgen --include-docstrings -p builtins generates

…
class str:
    …
    def strip(self, *args, **kwargs):
        """Return a copy of the string with leading and trailing whitespace removed.

        If chars is given and not None, remove characters in chars instead."""
    …

whereas using the typeshed annotations it might instead look like

class str(Sequence[str]):
    …
    @overload
    def strip(self: LiteralString, chars: LiteralString | None = None, /) -> LiteralString:
        """Return a copy of the string with leading and trailing whitespace removed.

        If chars is given and not None, remove characters in chars instead."""

    @overload
    def strip(self, chars: str | None = None, /) -> str:  # type: ignore[misc]
        """Return a copy of the string with leading and trailing whitespace removed.

        If chars is given and not None, remove characters in chars instead."""
…

Apologies
I'm new to the mypy project, so please feel to close this if it is out of scope or if I have misunderstood your aim with stubgen. My particular use case is using this in pyright to get proper stdlib stub docstrings; it imports these from typeshed whose stubs don't include docstrings. (See typeshed discussion here.)