Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

automodule to generate toc in sphinx documents

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.

like image 872
scphantm Avatar asked Feb 03 '15 19:02

scphantm


People also ask

What is Toctree Sphinx?

The toctree directive is the central element. Note. Simple “inclusion” of one file in another can be done with the include directive.

What is Sphinx Apidoc?

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.

How do I use autodoc in Sphinx?

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.

How does the Sphinx autosummary extension work?

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.

How to add Sphinx documentation to Python code?

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.

How do I autogenerate the RST files in Sphinx?

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.


1 Answers

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'
like image 140
coldfix Avatar answered Oct 18 '22 18:10

coldfix