Skip to main content

Add a succinct TOC to auto-documented classes.

Project description

https://img.shields.io/pypi/v/autoclasstoc.svg https://img.shields.io/pypi/pyversions/autoclasstoc.svg https://img.shields.io/readthedocs/autoclasstoc.svg

It’s surprisingly difficult to document large Python classes in a way that’s easy for users to navigate. Most projects use the autodoc Sphinx plugin, which simply puts the complete documentation for each class member one after another. While this does fully document the class, it doesn’t give the user a quick way to see everything the class can do. This makes classes of even moderate complexity difficult to navigate. It also encourages projects to be stingy about which class members to include in the documentation (e.g. excluding special methods, inherited methods, private methods, and/or undocumented methods), to the further detriment of the user.

What’s needed is for each class to have a succinct table of contents (TOC) that:

  • Is organized into sections that will be meaningful to the user. Different projects and classes may call for different sections, e.g. public/private methods, methods that share a decorator, methods with a common prefix, etc.

  • Includes every method of the class (so that the documentation is complete), while still making it easy for the user to get a sense for what the class does and find what they’re looking for.

  • Collapses inherited methods. Complex classes in particular can inherit a lot of methods from their parent classes, and while these methods should be present in the TOC (since they’re part of the class), collapsing them makes it easier for the user to grok the functionality provided by the class itself.

autoclasstoc provides a new Restructured Text directive that is all of these things. It also works well with autodoc and autogen, and should be easy to incorporate into any existing project.

See the complete documentation for more information (including examples).

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

autoclasstoc-1.2.0.tar.gz (20.3 kB view details)

Uploaded Source

Built Distribution

autoclasstoc-1.2.0-py2.py3-none-any.whl (11.2 kB view details)

Uploaded Python 2Python 3

File details

Details for the file autoclasstoc-1.2.0.tar.gz.

File metadata

  • Download URL: autoclasstoc-1.2.0.tar.gz
  • Upload date:
  • Size: 20.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.24.0 setuptools/47.1.1 requests-toolbelt/0.9.1 tqdm/4.46.1 CPython/3.7.7

File hashes

Hashes for autoclasstoc-1.2.0.tar.gz
Algorithm Hash digest
SHA256 8d1445a5af965224d53500c4375be369064a798a6e7dae308d0286c42602a683
MD5 680c849592d03b74744073f802f24289
BLAKE2b-256 93730995a1d93e51be8f43e8c4bbd4f8cfcda7901f7076998160bacb581381c6

See more details on using hashes here.

File details

Details for the file autoclasstoc-1.2.0-py2.py3-none-any.whl.

File metadata

  • Download URL: autoclasstoc-1.2.0-py2.py3-none-any.whl
  • Upload date:
  • Size: 11.2 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.24.0 setuptools/47.1.1 requests-toolbelt/0.9.1 tqdm/4.46.1 CPython/3.7.7

File hashes

Hashes for autoclasstoc-1.2.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 6a1d312d1db89ac2e9ff6f43f6eebd6fdee4a46920375cfe1c03af522f781c99
MD5 fd2533efdf8865b33af35fc61293c9a8
BLAKE2b-256 640475754ba896d0029a6ba091e452ad816c2584c5925afa514469fbbf918129

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page