覆盖 sphinx autodoc 中的函数声明

Question

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

#!/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 文件，其中包含如下代码片段：

mymodule.foobar.foobar = '这里有一些荒谬又长又难看的正则表达式'

此处有额外文档

mymodule.myfunc(val='这里有一些荒谬又长又难看的正则表达式')

巴拉巴拉巴拉

基于这篇stackoverflow帖子，我想我可以通过将我的模块更改为：

来更改它

#!/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。）

Answer 1

您有一个模块级变量，用作函数中关键字参数的默认值。 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) 

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