search

mitmproxy / pdoc

API Documentation for Python Projects
https://pdoc.dev
MIT No Attribution
1.94k stars 193 forks source link

Support for typing @overload annotation #442

Open jpfeuffer opened 2 years ago

jpfeuffer commented 2 years ago

Problem Description

Some support for function overloads specified by @overload annotation in typestubs is missing. All functions that have it, are just shown with the general base implementation (*args, **kwds) instead of the declared and fully typed overloads.

Proposal

In the beginning, just one entry per overload would be nice.

Additional context

Trying to document a Cython extension that due to its C++ origin has typestubs with @overload annotations

mhils commented 2 years ago

pdoc heavily relies on dynamic analysis. As far as I know, you cannot access @overload signatures using that approach (the final function definition overwrites all previous ones). Implementing support using static analysis would be a major undertaking and introduce significant complexity. I think your request is by all means valid, but I'm afraid the answer here is to 1) use a different documentation generator, 2) not use @overload, or 3) live with it.

jpfeuffer commented 2 years ago

I see. That makes sense. Do you by chance know about any documentation tool that supports both typestubs and overloads 😅 It is surprisingly hard to find.

Btw: It might be possible starting from 3.11. https://github.com/python/cpython/issues/89263

mhils commented 2 years ago

Seems like this hasn't made it into 3.11 in time and will be in 3.12 the earliest.

I see. That makes sense. Do you by chance know about any documentation tool that supports both typestubs and overloads

I don't know, but Sphinx and maybe mkdocstrings have the largest ecosystems.

jpfeuffer commented 2 years ago

Yes, not in the help() function but maybe via the typing stdlib (typing.getOverloads()). The PR for that was merged early enough I think.

Anyway, I give up for now and will revisit the whole thing in the very distant future again. (Sphinx autosummary/doc does not support type stubs at all and overloads only via docstrings and without descriptions of each overload).

Thanks for considering!