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 ='这里有一些荒谬冗长且丑陋的正则表达式）

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也在GitHub上提交了an issue ticket。

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

使用autofunction覆盖.rst文件中的签名，如the answer中对链接问题所述。
如果docstring的第一行看起来像签名，并且autodoc_docstring_signature配置变量设置为True（默认情况下是这样），那么Sphinx将使用该行作为签名。

因此，如果您的文档字符串如下所示，
```
def myfunc(val=foobar):
    '''myfunc(val=foobar)

    Blah blah blah'''
    pass
```
它应该以你想要的方式工作。

在问题中，你在docstring中有第一行：
```
.. function:: my_module.myfunc(val=foobar) 
```
这不起作用，因为它看起来不像是一个合适的签名。

在sphinx的autodoc中覆盖函数声明

1 个答案: