PEP 727: Documentation Metadata in Typing

Thanks all for the discussion and feedback here!

Some final updates to hopefully, finally, finish this discussion.

PEP 727 is now withdrawn.

@Jelle helped me handle updating that part, as it was taking me some time to get back to this.

It seems the current best approach is to keep this idea out of the standard library, as a third-party tool, with a much more constrained scope.

I just published GitHub - fastapi/annotated-doc: Document parameters, class attributes, return types, and variables inline, with Annotated. for this, just for my tools (FastAPI, etc), and whoever, if anyone, wants to re-use the same idea.

I migrated FastAPI to use this new annotated_doc.Doc. This would make it easier for the typing_extensions team to decide if, when, and how to deprecate and remove Doc from there.

@pawamoy also just added support for annotated-doc in GitHub - mkdocstrings/griffe-typingdoc: Griffe extension for PEP 727 – Documentation Metadata in Typing. (that was fast :smiling_face_with_sunglasses:), so that the FastAPI reference docs continue to work normally.

I’ll continue to use this idea and this new small tool for my own projects, but now as an external effort with a much smaller scope, in my own constrained corner of Python, so it shouldn’t affect anyone concerned here about having this in the standard library.

Thanks all! :hot_beverage:

6 Likes