sphinx.ext.autodoc:保持签名中的常量名称

Question

我正在使用Sphinx的autodoc功能来记录我的API.

例:

DEFAULT_OPTION = 'default'
def do_something(msg, option=DEFAULT_OPTION):
    print msg

生成的文档现在显示以下签名:

do_something(msg, option='default')

如何告诉Sphinx保留常量值的名称,即

do_something(msg, option=DEFAULT_OPTION)

？

有没有我忽略的选择？如果可能的话,我不想再用手写所有的签名.

Answer 1

从 Sphinx 4.0 版本开始，有一个新的配置选项 ( autodoc_preserve_defaults)。环境

autodoc_preserve_defaults = True

您conf.py将保留源代码中的默认值。

Answer 2

您可能必须在 reST 文件中手动覆盖签名。

很难想出更好的答案。Autodoc 导入它所记录的模块，因此所有模块级代码（包括默认函数参数）都会被执行。

另请参阅这些类似的问题：此处和此处。

更新：

我刚刚意识到还有另一种选择。您可以通过将签名作为文档字符串的第一行来覆盖签名。请参阅autodoc_docstring_signature配置变量的文档以及此答案。