sphinx.ext.autodoc：在签名中保留常量名称 [英] sphinx.ext.autodoc: Keeping names of constants in signature

问题描述

我正在使用Sphinx的自动文档功能来记录我的API。

I'm using Sphinx's autodoc feature to document my API.

示例：

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

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

The generated documentation now shows the following signature:

do_something(msg, option='default')

我如何告诉Sphinx保持常量值的名称，即

How can I tell Sphinx to keep the name of the constant value i.e.

do_something(msg, option=DEFAULT_OPTION)

？

我有没有忽略的选择？

Is there an option I have overlooked? If at all possible, I'd like NOT to write all signature by hand again.

推荐答案

您可能不得不在reST文件中手动覆盖签名。

很难提出一个更好的答案。 Autodoc会导入其文档中的模块，因此将执行所有模块级代码（包括默认函数参数）。

It's hard to come up with a better answer. Autodoc imports the modules it documents, so all module-level code (including default function arguments) is executed.

另请参阅以下类似问题：此处和此处。

See also these similar questions: here and here.

更新：

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

I just realized that there is another option. You can override the signature by including it as the very first line of the docstring. See the documentation of the autodoc_docstring_signature configuration variable, and this answer.

这篇关于sphinx.ext.autodoc：在签名中保留常量名称的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！