8000 Discrepancy in argument naming for Sphinx docs & help in the cmath module · Issue #125957 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
skirpichev opened this issue Oct 25, 2024 · 0 comments
Closed

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

skirpichev opened this issue Oct 25, 2024 · 0 comments
Labels
docs Documentation in the Doc dir

Comments

@skirpichev
Copy link
Contributor
skirpichev commented Oct 25, 2024 •
edited by bedevere-app bot
Loading

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
@skirpichev skirpichev added the docs Documentation in the Doc dir label Oct 25, 2024
@skirpichev 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 Oct 25, 2024
skirpichev added a commit to skirpichev/cpython that referenced this issue Oct 25, 2024
@skirpichev
pythongh-125957: sync argument naming in sphinx docs of the cmath and…
769c65f 
… help()
@bedevere-app bedevere-app bot mentioned this issue Oct 25, 2024
Merged
AA-Turner pushed a commit that referenced this issue Apr 1, 2025
@skirpichev @picnixz
gh-125957: sync argument naming in sphinx docs of the cmath and help…
0a3eb88 
…() (#125958)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Apr 1, 2025
@skirpichev @picnixz @miss-islington
pythongh-125957: sync argument naming in sphinx docs of the cmath and…
eb05118 
… help() (pythonGH-125958)

(cherry picked from commit 0a3eb88)

Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Apr 1, 2025
@skirpichev @picnixz @miss-islington
pythongh-125957: sync argument naming in sphinx docs of the cmath and…
58dbb66 
… help() (pythonGH-125958)

(cherry picked from commit 0a3eb88)

Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
This was referenced Apr 1, 2025
Merged
Merged
AA-Turner pushed a commit that referenced this issue Apr 1, 2025
@miss-islington @skirpichev @picnixz
[3.13] gh-125957: sync argument naming in sphinx docs of the cmath an…
2745984 
…d help() (GH-125958) (#131962)

gh-125957: sync argument naming in sphinx docs of the cmath and help() (GH-125958)
(cherry picked from commit 0a3eb88)

Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
AA-Turner pushed a commit that referenced this issue Apr 1, 2025
@miss-islington @skirpichev @picnixz
[3.12] gh-125957: sync argument naming in sphinx docs of the cmath an…
ce85eb5 
…d help() (GH-125958) (#131963)

gh-125957: sync argument naming in sphinx docs of the cmath and help() (GH-125958)
(cherry picked from commit 0a3eb88)

Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
seehwan pushed a commit to seehwan/cpython that referenced this issue Apr 16, 2025
@skirpichev @picnixz @seehwan80
pythongh-125957: sync argument naming in sphinx docs of the cmath an…
61f0c36 
…d help() (python#125958)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
@hugovk 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 May 21, 2025
@hugovk hugovk closed this as completed May 21, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Documentation in the Doc dir
Projects
docs issues
Status: Todo
Milestone
No milestone
Development

No branches or pull requests
2 participants
@hugovk @skirpichev
0