Automate adding Type Annotations to Documentation

[cooperlees]

BPO	39204
Nosy	@gvanrossum, @brettcannon, @rhettinger, @ilevkivskyi, @cooperlees, @pablogsal, @tirkarthi

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-01-03.19:12:25.475>
labels = ['type-feature', 'library', '3.9']
title = 'Automate adding Type Annotations to Documentation'
updated_at = <Date 2020-01-10.18:56:07.158>
user = 'https://github.com/cooperlees'

bugs.python.org fields:

activity = <Date 2020-01-10.18:56:07.158>
actor = 'levkivskyi'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2020-01-03.19:12:25.475>
creator = 'cooperlees'
dependencies = []
files = []
hgrepos = []
issue_num = 39204
keywords = []
message_count = 6.0
messages = ['359249', '359274', '359275', '359276', '359446', '359449']
nosy_count = 7.0
nosy_names = ['gvanrossum', 'brett.cannon', 'rhettinger', 'levkivskyi', 'cooperlees', 'pablogsal', 'xtreak']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue39204'
versions = ['Python 3.9']

[cooperlees]

What are people's thoughts on automating adding type annotations to documentation now that Typeshed is mature and Python 2 is EOL?
(Let us never speak of comment annotations)

[tirkarthi]

I am not sure if it was discussed earlier there was a discussion on adding PEP-570 syntax across the docs. This comes at the cost of keeping the types updated. There was also a poc over expanding the signature to view the PEP-570 syntax as needed.

bpo-37134
https://bugs.python.org/msg344654

[tirkarthi]

Some discussion on similar proposal earlier : https://mail.python.org/pipermail/python-dev/2017-November/150234.html

[gvanrossum]

This was never blocked on Python 2 (at best we'd do this for the most recent Python 3 release anyway).

I expect it will be quite complex to get the quality of the implementation high enough, but I suppose someone should start with a prototype. I'm not volunteering though. :-)

[brettcannon]

I think a bigger thing is to simply get type annotations to be used in the stdlib first, then we can worry about documenting them as part of the API. :)

[gvanrossum]

Actually I agree with the OP that we could get some mileage out of joining typeshed with the docs, regardless of whether there are annotations in the stdlib.