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.

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

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

Comments

@skirpichev
Copy link
Contributor
skirpichev commented Oct 25, 2024

For example, cmath.sin docs looks like:

.. 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
AA-Turner pushed a commit that referenced this issue Apr 1, 2025
…() (#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
… 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
… 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>
AA-Turner pushed a commit that referenced this issue Apr 1, 2025
…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
…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
…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
Labels
docs Documentation in the Doc dir
Projects
Status: Todo
Development

No branches or pull requests

2 participants
0