是否可以为特定功能覆盖Sphinx autodoc？

Question

我正在使用Sphinx的autodoc插件自动记录一组模块。 我有一个接受*args的函数，我想覆盖文档以显示Python stdlib文档使用的稍微好一点的funcname(arg1[, arg2[, ...]])样式。

是否可以覆盖特定功能的autodoc输出？

Answer 1

可以使用autofunction覆盖签名：

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

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

但是，具有重写签名的函数不会与使用automodule的其他函数一起automodule 。 对每个函数使用显式autofunction函数指令可以解决这个问题：

.. autofunction:: firstfunc

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

.. autofunction:: thirdfunc

加成

您还可以附加到docstring：

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

   Extra documentation here.  

要覆盖签名和docstring，请使用function而不是autofunction 。

增加2

签名也可以通过将签名作为函数docstring的第一行来覆盖。 有关详情，请参阅此答案 。