重写斯芬克斯的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

...and，我有一个.rst文件，其内容如下：

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

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

当我构建文档时，我会得到一个html文件，其中包含一个代码片段，如下所示：

mymodule.foobar.foobar =“这里的一些荒谬的长而丑陋的正则表达式” 这里的额外文件 mymodule.myfunc(val='Some荒诞而又丑陋的regex在这里‘) 废话废话

基于此堆叠溢流柱，我认为可以通过将模块更改为：

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

...but并没有做到这一点，只是把我想要的签名作为身体的一部分附加在丑陋的签名下面。有人知道我怎么才能正确地覆盖这个吗？

(我使用的是狮身人面像v1.1.3，顺便说一下。)

Answer 1

您有一个模块级变量，用作函数中关键字参数的默认值。Sphinx在函数签名中显示该变量的值(而不是名称)。这个问题在另一个问题中进行了讨论，OP还在GitHub上提交了关于这个问题的报告。

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

1. 通过使用.rst文件重写autofunction文件中的签名，如答案中对链接问题的解释。
2. 如果docstring的第一行看起来像一个签名，并且如果签名配置变量被设置为True (默认情况下)，那么Sphinx将使用该行作为签名。 所以如果您有一个如下所示的docstring， def myfunc(val=foobar)：“myfunc(val=foobar) Blah”“通行证” 它应该以你想要的方式工作。 在这个问题中，您在docstring中有以下第一行： 。。功能: my_module.myfunc(val=foobar) 这是不起作用的，因为它看起来不像一个适当的签名。