Basic Usage

Follow these steps to start using autoclasstoc in your project:

  1. Install autoclasstoc from PyPI:

    $ pip install autoclasstoc
    
  2. Enable the autoclasstoc and sphinx.ext.autosummary extensions for your Sphinx project. The latter is required because autoclasstoc uses it to create the TOC. The snippet below also enables sphinx.ext.autodoc and sphinx.ext.viewcode to demonstrate a typical configuration, but neither of these extensions are required:

    conf.py
    extensions = [
            ...
            'autoclasstoc',
            'sphinx.ext.autodoc',
            'sphinx.ext.autosummary',
            'sphinx.ext.viewcode',
            ...
    ]
    

    You may also want to configure autoclass to include documentation for every member of every class by default (see below). Some projects shy away from doing this because including too many “unimportant” methods can hide the “important” ones, but this is much less of a concern with autoclassdoc. The TOC will make it easy for users to find the methods they’re looking for even in classes with lots of documentation (see the collections.Counter example).

    conf.py
    autodoc_default_options = {
        'members': True,
        'special-members': True,
        'private-members': True,
        'inherited-members': True,
        'undoc-members': True,
        'exclude-members': '__weakref__',
    }
    
  3. Use the autoclasstoc directive to add a TOC to a class. Follow the link for a full description of the directive, but typical usage is pretty straight-forward. For example, consider the Example class in the following snippet:

    class Parent:
    
        def inherited_method(self):
            """Duis lacus metus, euismod ut viverra sit amet, pulvinar sed urna."""
            pass
    
    class Example(Parent):
        """
        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    
        Nam justo sem, malesuada ut ultricies ac, bibendum eu neque. Lorem ipsum 
        dolor sit amet, consectetur adipiscing elit. Aenean at tellus ut velit 
        dignissim tincidunt. Curabitur euismod laoreet orci semper dignissim. 
        Suspendisse potenti. 
        """
    
        def __init__(self):
            """Vivamus sed enim quis dui pulvinar pharetra."""
            pass
    
        def documented_method(self):
            """
            Duis condimentum ultricies ipsum, sed ornare leo vestibulum vitae. 
    
            Sed ut justo massa, varius molestie diam. Sed lacus quam, tempor in 
            dictum sed, posuere et diam. Maecenas tincidunt enim elementum turpis 
            blandit tempus. Nam lectus justo, adipiscing vitae ultricies egestas, 
            porta nec diam. Aenean ac neque tortor. 
            """
            pass
    
        def undocumented_method(self):
            pass
    
        def _private_method(self):
            """Cras tempus lacus nec leo ultrices suscipit."""
            pass
    

    We can document this class using autoclasstoc as follows:

    .. autoclass:: basic_example.Example
       :members:
       :special-members:
       :private-members:
       :inherited-members:
    
       .. autoclasstoc::
    
    class basic_example.Example[source]

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

    Nam justo sem, malesuada ut ultricies ac, bibendum eu neque. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean at tellus ut velit dignissim tincidunt. Curabitur euismod laoreet orci semper dignissim. Suspendisse potenti.

    Public Methods:

    __init__()

    Vivamus sed enim quis dui pulvinar pharetra.

    documented_method()

    Duis condimentum ultricies ipsum, sed ornare leo vestibulum vitae.

    undocumented_method()

    Inherited from Parent

    inherited_method()

    Duis lacus metus, euismod ut viverra sit amet, pulvinar sed urna.

    Private Methods:

    _private_method()

    Cras tempus lacus nec leo ultrices suscipit.


    __init__()[source]

    Vivamus sed enim quis dui pulvinar pharetra.

    _private_method()[source]

    Cras tempus lacus nec leo ultrices suscipit.

    documented_method()[source]

    Duis condimentum ultricies ipsum, sed ornare leo vestibulum vitae.

    Sed ut justo massa, varius molestie diam. Sed lacus quam, tempor in dictum sed, posuere et diam. Maecenas tincidunt enim elementum turpis blandit tempus. Nam lectus justo, adipiscing vitae ultricies egestas, porta nec diam. Aenean ac neque tortor.

    inherited_method()

    Duis lacus metus, euismod ut viverra sit amet, pulvinar sed urna.