Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Sphinx extension to automatically generate autosummary tables for Python packages

Project description


This is a Sphinx extension that makes it possible to automatically generate API documentation for deeply nested Python packages using the built-in autosummary extension.

The problem with the built-in autosummary directive is that it does not automatically pick up nested sub-modules, requiring tedious manual work to specify the entire module tree.

Instead of this:

.. autosummary::
   :toctree: _autosummary


You can now simply use this:

.. autopackagesummary:: mypackage
   :toctree: _autosummary


To make use of this extension, the following steps are needed:

  1. Install the module using pip.
pip install sphinx-autopackagesummary
  1. Enable it in
extensions = ['sphinx.ext.autosummary', 'sphinx_autopackagesummary']

autosummary_generate = True
  1. Make use of the new syntax


The autopackagesummary directive accepts all options that are supported by autosummary, which are simply passed on.

To exclude packages from being imported, add them to the config setting autosummary_mock_imports.

Recursive generation

If your packages have subpackages, it is possible to use this recursively by customizing the autosummary template. For example, you could have your root package documented like so:

.. py:package:: mypackage

   This is my package.

   .. autopackagesummary:: mypackage
      :toctree: _autosummary
      :template: autosummary/package.rst

And then create a _templates/autosummary/package.rst like so:

{{ fullname | escape | underline }}

.. automodule:: {{ fullname }}

   .. autopackagesummary:: {{ fullname }}
      :toctree: .
      :template: autosummary/package.rst

Alternatively, you can override the default module.rst template.

Note the use of . for the toctree setting: otherwise, the _autosummary directories would keep nesting, like _autosummary/_autosummary/module.rst.


This extension has been placed into the public domain. If you make a contribution to this repository, you are placing your modifications into the public domain as well.

Project details

Download files

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

Files for sphinx-autopackagesummary, version 1.3
Filename, size File type Python version Upload date Hashes
Filename, size sphinx_autopackagesummary-1.3-py3-none-any.whl (3.8 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page