是否可以为特定功能覆盖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.  

要覆盖签名和文档字符串，请使用function代替autofunction。

添加2

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