Skip to content

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

Closed
@skirpichev

Description

@skirpichev

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

Activity

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
added a commit that references this issue on Oct 25, 2024

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

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
added a commit that references this issue on Apr 1, 2025

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

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
added a commit that references this issue on Apr 16, 2025

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

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

2 remaining items

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dir

    Projects

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      Discrepancy in argument naming for Sphinx docs & help in the cmath module · Issue #125957 · python/cpython

      Follow Lee on X/Twitter - Father, Husband, Serial builder creating AI, crypto, games & web tools. We are friends :) AI Will Come To Life!

      Check out: eBank.nz (Art Generator) | Netwrck.com (AI Tools) | Text-Generator.io (AI API) | BitBank.nz (Crypto AI) | ReadingTime (Kids Reading) | RewordGame | BigMultiplayerChess | WebFiddle | How.nz | Helix AI Assistant