Discrepancy in argument naming for Sphinx docs & help in the cmath module

[skirpichev]

For example, cmath.sin docs looks like:

cpython/Doc/library/cmath.rst

Lines 147 to 149 in 2513593

	.. function:: sin(x)
	Return the sine of *x*.

while help() shows:

>>> help(cmath.sin)
Help on built-in function sin in module cmath:

sin(z, /)
    Return the sine of z.

Note that help() has the "/" to show, that the parameter name is not a part of API (positional-only parameter), but the sphinx docs miss that part.

I think it's a good idea to sync parameter naming in help and sphinx. Note that the introduction in sphinx docs uses z to denote complex numbers, just as many textbooks.

Also, per PDEB decision, sphinx docs should include a slash to denote positional-only arguments. I propose instead allow positional-or-keyword arguments for functions of this module. In this way we can preserve simple (e.g. sin(z)) function signatures, while preserving "precision and completeness" of reference docs.

Linked PRs

• gh-125957: sync argument naming in sphinx docs of the cmath and help() #125958
• [3.13] gh-125957: sync argument naming in sphinx docs of the cmath and help() (GH-125958) #131962
• [3.12] gh-125957: sync argument naming in sphinx docs of the cmath and help() (GH-125958) #131963