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

[Paul Ganssle]

Paul Ganssle <p.ganssle at gmail.com> added the comment:

> I respectfully disagree with logic, "the language now permits this, so we should change all the docs to display it everywhere".  That moves it from optional knowledge to mandatory knowledge, from a day ten lesson to a day one lesson, from "once in a while, a user may benefit from being able to mark arguments as positional-only" to the category of "every single user will see this every time they see the docs".  There is a huge difference.

A decent part of the reasoning for the PEP was actually to create a standard way to document when arguments to a function are positional-only. By adopting the notation (already used in the numpy documentation IIRC), it makes a concise documentation clear.

Another part of the PEP's reasoning was that this notation is difficult to understand at least partially because it is rarely encountered, so "people don't understand it" as a reason to exclude it from the documentation becomes a bit of a self-fulfilling prophecy.

I am not really an expert in documentation and front-end design, but maybe it would be possible to have some sort of unobtrusive tooltip that activates on signatures that contain positional-only arguments?

----------
nosy: +p-ganssle

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