11

我有一个类似这样的模块：

#!/usr/bin/env python

#: Documentation here.
#: blah blah blah
foobar = r'Some really long regex here.'

def myfunc(val=foobar):
    '''Blah blah blah'''
    pass

...我有一个.rst文件是这样的：

:mod:`my_module` Module
-----------------------

..automodule:: my_module
    :members:
    :private-members:
    :show-inheritance:

当我构建文档时，我得到一个带有如下代码段的 html 文件：

我的模块.foobar。foob​​ar = '这里有一些荒谬的长而丑陋的正则表达式'

这里有额外的文档

我的模块。myfunc ( val='这里有一些又长又丑的正则表达式' )

等等等等等等

基于this stackoverflow post，我认为可以通过将模块更改为：

#!/usr/bin/env python

#: .. data:: my_module.foobar
#: Extra documentation here
foobar = 'Some really long regex here.'

def myfunc(val=foobar):
    '''.. function:: my_module.myfunc(val=foobar)

    Blah blah blah'''
    pass

...但这并没有奏效，只是将我想要的签名附加在丑陋的签名下面作为身体的一部分。有人知道我如何正确地覆盖它吗？

（我正在使用 Sphinx v1.1.3，顺便说一句。）

4

1 回答 1

17

您有一个模块级变量，用作函数中关键字参数的默认值。Sphinx 在函数签名中显示该变量的值（而不是名称）。这个问题在另一个问题中讨论过，OP 也已经在 GitHub 上提交了一个关于它的问题票。

但是，您可以通过两种方式解决此问题：

  1. autofunction如链接问题的答案中所述，使用 覆盖 .rst 文件中的签名。

  2. 如果文档字符串的第一行看起来像一个签名，并且autodoc_docstring_signature配置变量设置为True（默认情况下），那么 Sphinx 将使用该行作为签名。

    因此，如果您有一个如下所示的文档字符串，

    def myfunc(val=foobar):
    '''myfunc(val=foobar)

    Blah blah blah'''
    pass

    它应该以您想要的方式工作。

    在问题中，您在文档字符串中有第一行：

    .. function:: my_module.myfunc(val=foobar)

    这不起作用，因为它看起来不像一个正确的签名。

于 2012-08-23T08:34:53.863 回答