Is it possible to override Sphinx autodoc for spec

问题:

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?

回答1:

It is possible to override a signature by using autofunction:

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

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

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

Addition

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.

Addition 2

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