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:
       #: This is a public attribute
       public_attribute = 1
       #: This is a private attribute
       _private_attribute = 2
   
       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:
   
      .. autoclasstoc::
   
   .. autoclass:: basic_example.Parent
      :members:
      :special-members:
      :private-members:
   
      .. autoclasstoc::
   

   class basic_example.Example

   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 Data Attributes:

   Inherited from Parent

   public_attribute

   This is a public attribute

   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 Data Attributes:

   Inherited from Parent

   _private_attribute

   This is a private attribute

   Private Methods:

   _private_method()

   Cras tempus lacus nec leo ultrices suscipit.

   ---

   __init__()

   Vivamus sed enim quis dui pulvinar pharetra.

   _private_method()

   Cras tempus lacus nec leo ultrices suscipit.

   documented_method()

   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.

   class basic_example.Parent

   Public Data Attributes:

   public_attribute

   This is a public attribute

   Public Methods:

   inherited_method()

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

   Private Data Attributes:

   _private_attribute

   This is a private attribute

   ---

   _private_attribute = 2

   This is a private attribute

   inherited_method()

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

   public_attribute = 1

   This is a public attribute