1

I'm unable to format a tuple as a default argument properly:

.. class:: OutputFunc(args=('value',))

This is displayed in the HTML output without the tuple parentheses args='value'.

If I add backslashes:

.. class:: OutputFunc(args=\('value',\))

they are rendered: args=\('value', \),

Update: I found this in the sphinx docs, probably there is no solution.

Default values for optional arguments can be given (but if they contain commas, they will confuse the signature parser)

bad_coder
  • 11,289
  • 20
  • 44
  • 72
VPfB
  • 14,927
  • 6
  • 41
  • 75

1 Answers1

1

There are a number of ways to solve this, the problem is particular to using a singleton tuple literal as default argument.

This is displayed in the HTML output without the tuple parentheses args='value'.

Using sphinx-build 3.5.2 with Python 3.9.0 the parentheses do render, only the comma disappears.

.. class:: OutputFunc(args=('value',))

enter image description here

One alternative is to use the tuple constructor instead of the literal.

.. class:: OutputFunc(args=tuple('value'))

enter image description here

It's worth mentioning the problem only happens when the literal is a singleton.

.. class:: OutputFunc(args=('value', 'value2'))

enter image description here

Finally a solution that retains the comma and the parenthesis is using an invisible Unicode character after the comma, in this example I used U+200B (the zero-with space character). However other characters could be used (credit to @mzjn the idea was taken from one of his posts.)

.. class:: OutputFunc(args=('value', insert U+200B ZWSP character here))

enter image description here

EDIT: After OP feedback.

Apparently using older sphinx-build versions adding more parameters will again cause the bug even with the zero-width whitespace. The easiest solution is updating to a recent Sphinx version in which case the above workaround works even if using multiple parameters.

.. class:: OutputFunc(args=('value',​), debug=False)

enter image description here

bad_coder
  • 11,289
  • 20
  • 44
  • 72
  • 2
    This seems like a legitimate bug in Sphinx that should be reported as such. – Karl Knechtel Apr 17 '21 at 05:23
  • @KarlKnechtel I agree (searching through GitHub there will probably be a number of them). This are edge cases related with the comma when there's only a whitespace around it, because it serves as a separator and the whitespaces are normally collapsed by docutils. However, this sort of minor bug can take a long time to solve and users searching will probably prefer having a direct hit on Stack Overflow than having to sift through GitHub. (It can take an unreasonable amount of time to work around something so simple.) – bad_coder Apr 17 '21 at 05:28
  • 2
    Only the workaround idea with zero-width space is helpful in my situation. It works for me in Sphinx 3.2, so I'm accepting your answer, thanks. BTW `tuple('value')` is `('v', 'a', 'l', 'u', 'e')`, should be `tuple(['value'])`. – VPfB Apr 17 '21 at 06:16
  • @bad_coder, I just accepted. Unfortunately I have bad news. It no longer works when other parameters are added. `OutputFunc(args=('value',), debug=False)` – VPfB Apr 17 '21 at 06:50
  • 1
    @VPfB just tried with the new signature and it works perfectly, update to the latest Sphinx version (there were lots of changes bundled in the last update). For example, in the original problem statement you said the parenthesis were missing but with my Sphinx version they resolved well. – bad_coder Apr 17 '21 at 06:56
  • When updating Sphinx take care that it has several dependencies (as you probably noticed when installing) and those packages should also be updated. – bad_coder Apr 17 '21 at 07:08