如何在 ..class :: 签名中包含一个元组作为默认参数?

How to include a tuple in a ..class :: signature as default argument?

我无法将元组正确格式化为默认参数:

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

这显示在 HTML 输出中,没有元组括号 args='value'

如果我添加反斜杠:

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

它们被渲染:args=\('value', \),

更新:我在 sphinx 文档中找到了这个,可能没有解决方案。

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

有很多方法可以解决这个问题,这个问题特别适用于使用 a singleton tuple literal 作为默认参数。

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

将 sphinx-build 3.5.2 与 Python 3.9.0 结合使用,括号会呈现,只有逗号消失。

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

一种替代方法是使用元组构造函数而不是文字。

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

值得一提的是,该问题仅在文字为单例时发生。

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

最后一个保留逗号和括号的解决方案是在逗号后使用不可见的 Unicode 字符,在这个例子中我使用了 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))

编辑: OP 反馈后。

显然使用旧的 sphinx-build 版本添加更多参数将再次导致错误,即使使用零宽度空格也是如此。最简单的解决方案是更新到最新的 Sphinx 版本,在这种情况下,即使使用多个参数,上述解决方法也能正常工作。

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