Feature: Recognition of PEP 727 Doc objects in type annotations.

[emcd]

Background/Disclaimer: PEP 727 is still in draft after more than a year; from the discussion around the proposal, it is not clear that it is going to be accepted as a Python standard. That said, a typing_extensions maintainer has indicated that Doc will remain available from within that package indefinitely.

Given that Tyro has typing_extensions as a dependency and Doc is supported via that package and given that Tyro is very Annotated-friendly, would you consider supporting the collection of attribute/parameter docstrings from Doc objects inside of PEP 593 extended annotations as an alternative to the existing methods? This opens the way for sharing documentation between a generated CLI and generated documentation without duplication of effort.

[brentyi]

Hi @emcd!

This opens the way for sharing documentation between a generated CLI and generated documentation without duplication of effort.

To clarify, isn't this already possible? Since we parse docstrings for generated CLI helptext.

I've followed PEP 727 and I'm not opposed to supporting it (would review a PR!), but since it seems like the PEP won't be accepted it's not something that I would encourage use of. If we add support for it I'd note in the documentation that standard docstring formats should be preferred over typing_extensions.Doc for new projects.

[emcd]

This opens the way for sharing documentation between a generated CLI and generated documentation without duplication of effort.

To clarify, isn't this already possible? Since we parse docstrings for generated CLI helptext.

You're right, @brentyi . I should've proofread what I wrote more closely. The missing adjectival phrase is "more robust and programmatically discoverable". Yes, docstring parsing is one way to get this information, and I fully acknowledge that Tyro, SimpleParsing, etc... have this capability. But, it is not as programmatically discoverable as documentation in an annotation... and it likely introduces an additional package dependency to the supply chain. Also, documentation in an annotation moves with the argument or attribute being documented, whereas it can be severed during a refactor if it is in a docstring. There is also the potential for documentation reuse with PEP 727 Doc objects, which does not really exist in docstrings, as they cannot be f-strings and one has to composite __doc__ attributes separately to get around this limitation.

I've followed PEP 727 and I'm not opposed to supporting it (would review a PR!), but since it seems like the PEP won't be accepted it's not something that I would encourage use of. If we add support for it I'd note in the documentation that standard docstring formats should be preferred over typing_extensions.Doc for new projects.

Understood. I'll look into this after I make a patch for the other feature I raised yesterday. Thanks for being receptive to the idea.