[docs] [issue37134] [EASY] Use PEP570 syntax in the documentation

[Carol Willing]

Carol Willing <willingc at gmail.com> added the comment:

Tim's message resonated with me. Confusing users is something that I believe that we wish to minimize. I confess that I had a similar reaction as Tim when I saw functions with a trailing `/`. What I did find helpful was adding to the middle of the parameter list as was done in Serihy's earlier PRs.

Since we are balancing technical accuracy with user confusion (docs and docstrings), I propose the following: 

1. Remove the trailing / from 3.8 documentation but leave the / if it occurs in the middle of the parameter list. This increases technical accuracy from pre-3.8 and gives users more time to get comfortable with the change (since end users have found this a confusing area with args kwargs *).

2. Add to the documentation in 3.8 section on positional only parameters a note box that describes that in many/all cases where a / is not specified at the end and no * is found in the parameter list that a trailing slash would be accurate.

3. Give users time to absorb the positional only change in 3.8. Perhaps writing a blog post that explains in detail.

4. Add the trailing / in 3.9 documentation to make consistent with docstrings or improve/create a better directive for function that provides a better accuracy and less confusion. A Sphinx extension may also be made to show a simple user-friendly view and with a click the fully accurate view.

----------

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