Skip to main content

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.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distribution

Supported by

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