[issue37134] Use PEP570 syntax in the documentation

[Brett Cannon]

Brett Cannon <brett at python.org> added the comment:

To help short-circuit this discussion and focus on the desired solution, the steering council came to a decision that can be seen at https://github.com/python/steering-council/issues/12#issuecomment-498874939 :

- for Python 3.8 specifically, we think it makes sense to continue to leave the slashes out of the documentation for the all parameters are positional-only case (i.e. "... , /)") and the all parameters are positional-only & keyword-only case (i.e. "..., /, *, ..." and "..., /, *args, ..."). This question can then be revisited for Python 3.9.

- however, we actively want to see them added for the cases where an API has a mixture of positional-only and positional-or-keyword args (i.e. "..., /, ...")

- we'd like to see the rendered documentation for function signatures enhanced to use tooltips to name the positional-only (bare "/"), keyword-only (bare "*"), additional positional args (named "*"), and additional keyword args (named "**") notations (hyperlinking to a glossary entry could also be interesting, but may be too visually noisy based on how the hyperlinks get rendered)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue37134>
_______________________________________