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

Question

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

是否可以覆盖特定函数的自动文档输出？

Answer 1

可以使用 autofunction 覆盖签名：

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

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

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

.. autofunction:: firstfunc

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

.. autofunction:: thirdfunc

添加

您还可以附加到文档字符串：

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

   Extra documentation here.  

要覆盖签名和文档字符串，请使用 function而不是自动函数。

添加 2

还可以通过将签名作为函数文档字符串的第一行来覆盖签名。有关详细信息，请参阅此答案。