autodocsumm

0.2.15 · active · verified Sun Apr 12

autodocsumm is a Sphinx extension that enhances `sphinx.ext.autodoc` by automatically generating summary tables, similar to `sphinx.ext.autosummary`. It creates a Table of Contents with lists of methods, classes, functions, and attributes for documented modules or classes. The library is actively maintained, with frequent releases to ensure compatibility with the latest Sphinx versions. The current version is 0.2.15.

Warnings

breaking autodocsumm frequently releases updates to maintain compatibility with new Sphinx versions. Using an `autodocsumm` version that is incompatible with your Sphinx installation can lead to build errors or unexpected documentation output.
Fix: Always ensure that your installed `autodocsumm` version explicitly supports your Sphinx major version. Check `autodocsumm`'s changelog or project page for specific Sphinx compatibility information (e.g., v0.2.15 supports Sphinx 9, v0.2.13 supports Sphinx 8).
breaking Prior to version 0.2.14, `autodocsumm` might encounter issues with `ObjectMember` related deprecations or removals in newer Sphinx versions, potentially causing documentation build failures.
Fix: Upgrade `autodocsumm` to version 0.2.14 or later to address compatibility issues related to `ObjectMember` changes in Sphinx.
gotcha Similar to `sphinx.ext.autodoc`, `autodocsumm` imports the Python modules it documents during the Sphinx build process. If your modules contain executable code with side effects outside of `if __name__ == '__main__'` blocks, this code will be executed when Sphinx builds the documentation.
Fix: Protect any code with side effects in modules intended for documentation by placing it within an `if __name__ == '__main__'` block.
gotcha By default, the autosummary tables generated by `autodocsumm` are typically placed at the end of the docstring sections for classes and methods. This might not be the desired visual placement for all users.
Fix: To customize the positioning of summary tables, use the `autoclasssumm` or `automodulesumm` directives directly inside class or module docstrings. For global sorting of sections within autosummary tables, use the `autodocsumm_section_sorter` configuration option (available since v0.2.12).

Install

pip install autodocsumm Install latest version

Imports

autodocsumm
```
extensions = [
    'sphinx.ext.autodoc',
    'autodocsumm'
]
```
autodocsumm is a Sphinx extension and is enabled by adding its name to the `extensions` list in `conf.py`, not via a direct Python import.

Quickstart

To enable `autodocsumm`, add `sphinx.ext.autodoc` and `autodocsumm` to the `extensions` list in your Sphinx `conf.py` file. Then, use the `:autosummary:` option with `autodoc` directives such as `automodule` or `autoclass` in your reStructuredText or MyST files to generate summary tables. You can also set `autodoc_default_options = {'autosummary': True}` in `conf.py` to activate it by default for all autodoc directives.

# In conf.py
extensions = [
    'sphinx.ext.autodoc',
    'autodocsumm'
]

# Optional: Make autosummary active by default for all autodoc directives
# autodoc_default_options = {'autosummary': True}

# In your .rst or .md file (e.g., module.rst)
..
.. automodule:: my_package.my_module
   :members:
   :autosummary:

.. autoclass:: my_package.my_module.MyClass
   :members:
   :autosummary:

view raw JSON →