Sphinx-Autosummary: Creating Cleaner API Navigation Menus

Removing package and module names from Sphinx Autosummary navigation menus

Removing package and module names from Sphinx Autosummary navigation menus

Sphinx generated API documentation with Autosummary showing just the names of the functions and modules within your package. Image by the author.

Creating documentation for you python package is essential, but at the same time, it can also be boring and tedious! However, providing detailed documentation can help both developers of your package and end users easily navigate the codebase and it’s functionality.

Once the appropriate docstrings have been added to all of your functions and classes, we can use the Sphinx library and the Autosummary extension to auto-document the API.

When Sphinx and Autosummary are run, you will get back summary tables for all of the documented objects within your code — including modules, classes and functions.

This helps create a nice concise overview of the key functionality and easier navigation for the end user.

However, when using Sphinx recently, I found that using the default settings creates very wordy API navigation menus — as seen in the image below.

Sphinx generated API documentation with Autosummary showing full path to functions within your package. Image by the author.

By tweaking some of the default templates that come with the Autosummary extension, we can make a navigation menu with shorter names like below.

Sphinx generated API documentation with Autosummary showing just the names of the functions and modules within your package. Image by the author.

This can make it easier to read, especially if you have multiple modules and nested submodules.

Within this article we will see how can modify a few lines of code within the default templates to improve the API reference navigation menus.

This is not a full guide on how to use the Sphinx library or how to setup Autosummary, for that I would recommend checking out the Sphinx documentation or the following video.

Setting Up Sphinx Autosummary and API Guide Folder Structure

The rest of this article assumes that you have already setup Autosummary for your project and that you are familiar with creating Sphinx documentation.

Within the docs folder, we need to create a few files and folders as detailed below:

_templates will be used to store our custom templates, which will add shortly.

└── library_name/
    └── docs/
        └── source/
            ├── _templates/
            ├── api_guide/
            │   └── index.rst
            ├── conf.py
            └── index.rst

_api_guide/ with an index.rst file. This is the location that the autosummary will output its contents. The index.rst file contains the autosummary directive and also points to the template file.

If we have multiple modules within our library, we need to add these in. In the example below, we have the arithmetic and geometry submodules listed. These will then be searched for docstrings.

##############
API Reference
##############

.. currentmodule:: calc_library

.. autosummary::
    :toctree: _autosummary/
    :template: module.rst
    :recursive:
    :nosignatures:

    arithmetic
    geometry

Copying the Default Autosummary Templates

As a starting point, we need navigate to the Sphinx folder within our Python AppData install folder. Within here, we need to go to ext\autosummary\templates\autosummary

Within this folder, there will be three template files.

Default Sphinx Autosummary templates. Image by the author.

Copy these into the _templates/ subfolder

.
└── library_name/
    └── docs/
        └── source/
            ├── _templates/
            │   ├── class.rst
            │   └── module.rst
            ├── api_guide/
            │   └── index.rst
            ├── conf.py
            └── index.rst

Modifying the Default Sphinx Autosummary Templates

Once the templates have been copied over, we need to make a few small adjustments to them.

With the module.rst template we need to update the reference to fullname in line 1, so that it displays name .

We also need to add in additional references to our class and module template files on lines 32 and 56.

Sphinx autosummary templates for modules before modification (left) and after modification (right) to remove package and module names from the API navigation menu. Image by the author.

Similarly, within the class.rst template

Sphinx autosummary templates for modules before modification (left) and after modification (right) to remove package and module names from the API navigation menu. Image by the author.

Recreating the API Reference Guide

Once these templates have been modified we can regenerate our Sphinx documentation either using the makefile command or using sphinx-build -b html source build command in the terminal.

When the help is viewed, we will now have cleaner navigation menu.

Sphinx generated API documentation with Autosummary showing just the names of the functions and modules within your package. Image by the author.

Summary

When generating Sphinx documentation, it is important that the menu systems are easy to navigate for the user. By default, when using the Autosummary extension, the generated menus include the full location of the object — all the way from the package name to the function name. This can create lengthy menu items.

One way of simplifying this is by changing the references from fullname to just name within the custom template files.

By modifying these templates we can shorten the menu items to show only the object name and improve the readability of the menu for the user.

Thanks for reading. Before you go, you should definitely subscribe to my content and get my articles in your inbox. You can do that here! Also, if you have enjoyed this content and want to show your appreciation, consider giving it a few claps.

In Plain English 🚀

Thank you for being a part of the In Plain English community! Before you go:

• Be sure to clap and follow the writer ️👏️️

• Follow us: X | LinkedIn | YouTube | Discord | Newsletter

• Visit our other platforms: Stackademic | CoFeed | Venture | Cubed

• More content at PlainEnglish.io