In Sphinx, is there a way to get the automodule directive to generate a TOC of the members in the class?
Right now I have
.. Contents::
.. topic:: Abstract
bla bla bla
.. automodule:: ServerCommHandler
:members:
:private-members:
:special-members:
:show-inheritance:
:inherited-members:
which works fine, but this module has a lot of methods in it and a toc pointing to the method would be really nice.
The toctree directive is the central element. Note. Simple “inclusion” of one file in another can be done with the include directive.
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.
The sphinx-autodoc command will automatically generate rst files with autodoc directives from your code. This command only needs to be run when a new module is added to the project. First, make sure that the sphinx.ext.autodoc extension is included in the extensions list in conf.py as described in the section above.
The sphinx.ext.autosummary extension does this in two parts: There is an autosummary directive for generating summary listings that contain links to the documented items, and short summary blurbs extracted from their docstrings. A autosummary directive also generates short “stub” files for the entries listed in its content.
Should the documentation in your code follow the Google Python Style Guide, you’ll need to append sphinx.ext.napoleon to the extensions list. 4. Auto-generate the rst Files Sphinx generates the HTML documentation from reStructuredText (rst) files.
To autogenerate the rst files, run the sphinx-apidoc command using the following syntax: In our example, the output directory is source , and the module directory is python.
The autodocsumm extension will allow autodoc directives (automodule, autoclass) to automatically add summary tables like those of the builtin autosummary extension.
It can be used as follows:
pip install autodocsumm
Then edit your conf.py
to add the extension:
extensions = [
'sphinx.ext.autodoc',
...,
'autodocsumm',
]
and add an :autosummary:
option to your autodoc directives, e.g.:
.. automodule: foo.bar
:autosummary:
If you want to have autosummary in effect for all your autodoc directives without explicitly adding them, you can do so from the conf.py
as follows:
autodoc_default_options = {
'autosummary': True,
}
This is particularly helpful if you dynamically generate your API pages with sphinx-apidoc which is not easily configurable to add :autosummary:
.
Full example of a conf.py
that autogenerates all API pages:
def setup(app):
from sphinx.ext import apidoc
app.connect('builder-inited', lambda _: apidoc.main([
'-o', './api', '-d2', '-feMT', '../src/PROJECT',
]))
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
'autodocsumm',
]
autodoc_default_options = {
'autosummary': True,
}
autodata_content = 'both'
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