是否可以覆盖Sphinx autodoc的特定功能？ [英] Is it possible to override Sphinx autodoc for specific functions?

问题描述

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

I'm using Sphinx's autodoc plugin to automatically document a set of modules. I have a function that accepts *args, and I'd like to override the documentation to show the slightly nicer funcname(arg1[, arg2[, ...]]) style that the Python stdlib docs use.

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

Is it possible to override the autodoc output for a specific function?

推荐答案

可以使用 autofunction 覆盖签名：

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

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

但是，带有覆盖签名的函数不会与通过 automodule 引入的其他函数进行排序。对每个函数使用显式的 autofunction 指令可解决以下问题：

However, the function with the overridden signature is not sorted with the other functions pulled in with automodule. Using explicit autofunction directives for every function works around that:

.. autofunction:: firstfunc

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

.. autofunction:: thirdfunc

添加

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

You can also append to the docstring:

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

   Extra documentation here.  

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

To override both signature and docstring, use function instead of autofunction.

加法2

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

The signature can also be overridden by having a signature as the first line of the function docstring. See this answer for details.

这篇关于是否可以覆盖Sphinx autodoc的特定功能？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！