python - 覆盖 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 = 'Some absurdly long and ugly regex here'

Extra documentation here

mymodule.myfunc(val='Some absurdly long and ugly regex here')

blah blah blah

基于此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。)

Answer 1

您有一个模块级变量，用作函数中关键字参数的默认值。 Sphinx 在函数签名中显示该变量的值(而不是名称)。 another question 中讨论了此问题，并且 OP 还提交了 an issue ticket在 GitHub 上了解它。

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

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

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

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

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

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

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

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

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