可以为特定函数重写Sphinx autodoc吗？

Question

我正在使用Sphinx的自动文档插件，来自动生成一组模块的文档。我有一个函数，它可以接收多个参数（用*args表示），我想修改这个函数的文档，让它显示得更好看一些，像Python标准库文档那样，用funcname(arg1[, arg2[, ...]])的格式。

请问，有办法为某个特定的函数修改自动文档的输出吗？

Answer 1

你可以通过使用 autofunction 来覆盖一个函数的签名：

.. automodule:: yourmodule
   :members:
   :exclude-members: funcname

.. autofunction:: funcname(arg1[, arg2[, ...]])

不过，使用 autofunction 覆盖的函数签名不会和通过 automodule 引入的其他函数一起排序。如果你对每个函数都使用明确的 autofunction 指令，就可以解决这个问题：

.. autofunction:: firstfunc

.. autofunction:: funcname(arg1[, arg2[, ...]])

.. autofunction:: thirdfunc

补充说明

你还可以在文档字符串中添加内容：

.. autofunction:: funcname(arg1[, arg2[, ...]])

   Extra documentation here.  

如果你想同时覆盖签名和文档字符串，可以用 function 替代 autofunction。

补充说明 2

你也可以通过在函数文档字符串的第一行写上签名来覆盖签名。详细信息请查看 这个回答。