Menu
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?
235
There are several different docstring formats which one can use in order to enable Sphinx's autodoc extension to automatically generate documentation. For this tutorial we will use the Sphinx format, since, as the name suggests, it is the standard format used with Sphinx.
sphinx-apidoc is a tool for automatic generation of Sphinx sources that, using the autodoc extension, document a whole package in the style of other automatic API documentation tools. MODULE_PATH is the path to a Python package to document, and OUTPUT_PATH is the directory where the generated sources are placed.
Sphinx AutoAPI provides "autodoc" style documentation for multiple programming languages without needing to load, run, or import the project being documented. In contrast to the traditional Sphinx autodoc, which is Python-only and uses code imports, AutoAPI finds and generates documentation by parsing source code.
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.
166
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
