是否可以为特定功能重写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拉入的其他函数一起排序。对每个函数使用显式的autofunction指令可以解决这个问题：

.. autofunction:: firstfunc

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

.. autofunction:: thirdfunc

添加

也可以附加到docstring：

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

   Extra documentation here.  

要同时重写签名和docstring，请使用function，而不是autofunction。

添加2

签名也可以通过将签名作为函数docstring的第一行来重写。有关详细信息，请参见this answer。