comma after leading optional argument in function signature

Chris Jerdonek avatarChris Jerdonek created an issue

If an optional argument is at the beginning of the parameter list of a function or method, the comma renders after the closing bracket as opposed to before it. Here is an example from the Python documentation (notice also that the comma for the final optional argument, in contrast, renders correctly inside the brackets):

range([start], stop[, step])

(from http://docs.python.org/dev/library/functions.html#func-range )

This should instead be--

range([start,] stop[, step]) (or perhaps range([start, ]stop[, step]) )

This occurs even though the corresponding reST documentation is correct:

.. function:: range([start,] stop[, step])

I poked around in the Sphinx code, and it is possible that this is a relevant area (the sphinx.domains.python._pseudo_parse_arglist() function):

https://bitbucket.org/birkenfeld/sphinx/src/1f3a2749df39/sphinx/domains/python.py#cl-37

Comments (7)

  1. Chris Jerdonek

    Given Sphinx's testing structure, what would be the proper way to add tests for changes to the _pseudo_parse_arglist() function that I referenced in the original comment? Would there be a way for me to add unit tests to test this individual function (or a related function) in isolation?

  2. Chris Jerdonek

    I attached a first attempt at a patch. It changes only the visit/depart logic in sphinx/writers/html.py.

    With the patch, all of the following functions for example render correctly (as shown below):

    foo(a)
    foo(a, b)
    foo([a])
    foo(a[, b])
    foo([a, ]b)
    foo([a, ]b, c)
    foo([a][, b])
    foo([a, ]b[, c])
    foo([a, ]b, c[, d])
    foo([a, ]b, c, [d, ]e)
    foo([a, ]b, c, [d, ]e[, f])
    foo([a, b])
    foo([a, b, ]c)
    foo(a[, b, c])
    foo(a[, b[, c]])
    foo(a, [b, [c, ]]d)
    foo(a=0[, b])
    foo(a, [b, ]c=0)
    foo(a, b=0[, c])
    foo(a, b=0, [c, ]d=0)
    foo(a, b=0[, c, d])
    

    Test cases for the test suite could be created from these.

  3. Log in to comment
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.