search

mitmproxy / pdoc

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

Support PEP 727 Annotated/Doc annotations? #755

Open jeremander opened 3 weeks ago

jeremander commented 3 weeks ago

Problem Description

PEP 727 proposes a standard syntax for applying documentation strings to function parameters, return values, class variables, etc. using Annotated/Doc. While the PEP has not yet been accepted (and may or may not be), some Python libraries like pydantic and FastAPI are already using it regardless.

Proposal

It would be nice if pdoc could support this, extracting Doc elements from Annotated type annotations and inserting the text into the appropriate section of the rendered documentation. This could be used in lieu of or in conjunction with existing docstring styles like Google or numpy.

Alternatives

I don't think any mainstream doc generators are supporting this syntax yet, but there is an extension for mkdocstrings that does seem to support it.

Additional context

If PEP 727 is accepted, then the typing module will introduce Doc. But otherwise, Doc is expected to remain in the 3rd party typing_extensions library indefinitely.

mhils commented 3 weeks ago

I'd be open to a well-written PR if the PEP gets accepted, but to be frank I'm not a fan of the syntax at all. So unless this becomes widely used, I don't want to maintain any of it. 🙊

jeremander commented 3 weeks ago

Understandable. I don't love the syntax either, but I do like the idea of docs-in-annotations generally. I guess we wait and see what happens in terms of adoption.