autodoc
¶
Sphinx autodoc hooks for documenting Invoke-level objects such as tasks.
Unlike most of the rest of Invocations, this module isn’t for reuse in the “import and call functions” sense, but instead acts as a Sphinx extension which allows Sphinx’s autodoc functionality to see and document Invoke tasks and similar Invoke objects.
Note
This functionality is mostly useful for redistributable/reusable tasks
which have been defined as importable members of some Python package or
module, as opposed to “local-only” tasks that live in a single project’s
tasks.py
.
However, it will work for any tasks that Sphinx autodoc can import, so in a
pinch you could for example tweak sys.path
in your Sphinx conf.py
to get it loading up a “local” tasks file for import.
To use:
Add
"invocations.autodoc"
to your Sphinxconf.py
’sextensions
list.Use Sphinx autodoc’s
automodule
directive normally, aiming it at your tasks module(s), e.g... automodule:: myproject.tasks
in some.rst
document of your choosing.As noted above, this only works for modules that are importable, like any other Sphinx autodoc use case.
Unless you want to opt-in which module members get documented, use
:members:
or add"members": True
to yourconf.py
’sautodoc_default_options
.By default, only tasks with docstrings will be picked up, unless you also give the
:undoc-members:
flag or add:undoc-members:
/ add"undoc-members": True
toautodoc_default_options
.Please see the autodoc docs for details on these settings and more!
Build your docs, and you should see your tasks showing up as documented functions in the result.