Description

skirpichev

opened on Oct 25, 2024

Issue body actions

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

Activity

1. skirpichev

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Oct 25, 2024
2. skirpichev

   changed the title [-]Disgrepancy in argument naming for sphinx docs & help in the cmath module[/-] [+]Discrepancy in argument naming for sphinx docs & help in the cmath module[/+] on Oct 25, 2024
3. skirpichev

   added a commit that references this issue on Oct 25, 2024

   pythongh-125957: sync argument naming in sphinx docs of the cmath and…

   769c65f
4. willingc

   added this to docs issueson Oct 31, 2024
5. github-project-automation

   moved this to Todo in docs issueson Oct 31, 2024
6. AA-Turner

   added a commit that references this issue on Apr 1, 2025

   gh-125957: sync argument naming in sphinx docs of the cmath and help…

   0a3eb88
7. miss-islington

   added 2 commits that reference this issue on Apr 1, 2025

   pythongh-125957: sync argument naming in sphinx docs of the cmath and…

   eb05118

   pythongh-125957: sync argument naming in sphinx docs of the cmath and…

   58dbb66
8. AA-Turner

   added 2 commits that reference this issue on Apr 1, 2025

   [3.13] gh-125957: sync argument naming in sphinx docs of the cmath an…

   2745984

   [3.12] gh-125957: sync argument naming in sphinx docs of the cmath an…

   ce85eb5
9. hugovk

   changed the title [-]Discrepancy in argument naming for sphinx docs & help in the cmath module[/-] [+]Discrepancy in argument naming for Sphinx docs & help in the cmath module[/+] on May 21, 2025
10. hugovk

    closed this as completedon May 21, 2025

Issue actions