-
-
Notifications
You must be signed in to change notification settings - Fork 32k
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
Labels
docs
Documentation in the Doc dir
Comments
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>
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>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
For example, cmath.sin docs looks like:
cpython/Doc/library/cmath.rst
Lines 147 to 149 in 2513593
while help() shows:
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
The text was updated successfully, but these errors were encountered: