Display docstrings correctly

[laurensvalk]

@dlech wrote.

FYI, to make autocompletion work correctly, stubs need to consider autocompletion first and documentation second. We can always "fake" the documentation by not using autoclass in the .rst files if needed.

For better autocompletion of standard library types, we should refer to typeshed. For example enumerate should be properly typed as https://github.com/python/typeshed/blob/6d6250f10963b8ad7aeeba387c8d48dc9d0cb92b/stdlib/builtins.pyi#L910.

[laurensvalk]

We can always "fake" the documentation by not using autoclass in the .rst files if needed.

Sphinx did not pick up overloading correctly when using autofunction so we might have to do a bit of hacking to make this work.

[laurensvalk]

For special cases we could have one definition for Sphinx and another for typing, perhaps using if/else or a decorator to make it pick the right one.

[laurensvalk]

For special cases we could have one definition for Sphinx and another for typing, perhaps using if/else or a decorator to make it pick the right one.

Sphinx seems to ignore such conditionals. For example, if you do:

if True:
    class complex:

           # overload init 3 times

else:
    class complex:

           # overload init 2 times

My idea was to pick one on Sphinx and the other for typing, but Sphinx just overloads it 5 times.

The same goes for conditionals within the class definition.

[laurensvalk]

As these special cases probably mostly apply to ubuiltins, maybe we could just have a dedicated typing file for this one.

[dlech]

Can we not override the signatures by putting the desired signature for documentation as the first line of the doc string? relevant docs

class complex:
    @overload
    def __init__(self, ...):
        ...

    @overload
    def __init__(self, ...):
        ...

    @overload
    def __init__(self, ...):
        ...

    def __init__(self, ...):
        """
        __init__(self, ...) \ __init__(self, ...)

        ...
        """

It also looks like there are some hooks for modifying the signature: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#event-autodoc-before-process-signature.

[laurensvalk]

Thanks! I did not know we could do overloading with this as well. This looks like it should work nicely.

[laurensvalk]

Can we not override the signatures by putting the desired signature for documentation as the first line of the doc string?

Apparently not in the version we are using, but it looks like it might work in 4.0, pending #70.

One caveat is that it appears to show None as a return type by default, which is a bit confusing for classes.

[laurensvalk]

Another thing I don't really like (even in the current version) is the lack of parenthesis for the signature without arguments. I know this the standard for classes in now, but it does not make sense in this overloaded context.

[laurensvalk]

It's also not going to solve things like enumerate being displayed as a class, but I think we can live with that for the upcoming release.

[laurensvalk]

The generics and guidelines are now resolved. We can make specific issues to fix the typing implementation of specific functions and classes.