覆盖autodoc中的sphinx函数声明

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。 foob​​ar = ‘这里有些长而丑陋的正则表达式’

额外的文档在这里

mymodule。 myfunc （ val =’这里有些长而丑陋的正则表达式’ ）

等等等等等等

基于这个帖子)，我认为可以通过将模块更改为以下内容来对其进行更改：

#!/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. 通过使用来覆盖.rst文件中的签名autofunction，如链接问题的答案中所述。

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

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

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

    Blah blah blah'''
    pass

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

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

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

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