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

编程问答 2022-05-14

问题描述

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

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

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

如果我添加反斜杠：

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

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

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

可以给可选参数的默认值（但如果它们包含逗号，它们会混淆签名解析器）

解决方法

有很多方法可以解决这个问题，问题是使用 a singleton tuple literal 作为默认参数。

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

在 Python 3.9.0 中使用 sphinx-build 3.5.2 时，括号会呈现，只有逗号消失。

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

enter image description here

另一种选择是使用元组构造函数而不是文字。

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

enter image description here

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

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

enter image description here

最后一个保留逗号和括号的解决方案是在逗号后使用一个不可见的 Unicode 字符，在这个例子中我使用了 U+200B (the zero-with space character)。但是也可以使用其他字符（归功于@mzjn，这个想法来自one of his posts。）

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

enter image description here

编辑：在 OP 反馈之后。

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

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

enter image description here