Creating Streamlined API Navigation Menus with Sphinx-Autosummary
Written on
Chapter 1: Introduction to Sphinx-Autosummary
Documenting your Python package is crucial, yet it can also feel monotonous and labor-intensive. Nevertheless, thorough documentation aids both developers and end-users in navigating the codebase and understanding its features. Once you've incorporated suitable docstrings into your functions and classes, you can leverage the Sphinx library alongside the Autosummary extension to automatically generate API documentation.
When you execute Sphinx and Autosummary, you'll receive summary tables for all documented entities, including modules, classes, and functions. This creates a succinct overview of essential functionalities, facilitating easier navigation for users.
However, I've noticed that the default settings in Sphinx produce overly verbose API navigation menus.
By adjusting some default templates associated with the Autosummary extension, we can create navigation menus with shorter names.
This approach enhances readability, especially when dealing with numerous modules and nested submodules.
In this article, we'll explore how to tweak a few lines of code within the default templates to enhance the API reference navigation menus. This is not a comprehensive guide on utilizing the Sphinx library or configuring Autosummary; for those topics, I recommend consulting the Sphinx documentation or watching the following video.
Setting Up Your Project Structure
This article presumes that you've already configured Autosummary for your project and are familiar with creating Sphinx documentation. In your docs folder, you need to create several files and directories as outlined below:
- _templates: This folder will contain our custom templates.
└── library_name/
└── docs/
└── source/
├── _templates/
├── api_guide/
│ └── index.rst
├── conf.py
└── index.rst
The _api_guide/ directory should have an index.rst file, which serves as the destination for the Autosummary output. This index.rst file includes the Autosummary directive and references the template file.
If your library has multiple modules, you'll need to include them in the following manner:
API Reference
| toctree: | _autosummary/ :template: module.rst :recursive: :nosignatures: |
|---|
arithmetic
geometry
Copying Default Autosummary Templates
First, navigate to the Sphinx folder within your Python AppData installation directory. From there, go to extautosummarytemplatesautosummary. You'll find three template files here.
Copy these files into the _templates/ subdirectory:
└── library_name/
└── docs/
└── source/
├── _templates/
│ ├── class.rst
│ └── module.rst
├── api_guide/
│ └── index.rst
├── conf.py
└── index.rst
Modifying the Default Autosummary Templates
After copying the templates, you'll need to make a few minor adjustments. In the module.rst template, update the reference from fullname to name in line 1 so that it displays just the name. Additionally, introduce references to our class and module template files on lines 32 and 56.
Similarly, apply changes within the class.rst template.
Recreating the API Reference Guide
Once you've made these modifications, regenerate your Sphinx documentation using the makefile command or the sphinx-build -b html source build command in your terminal. When you check the documentation, you should now see a cleaner navigation menu.
Summary
When generating Sphinx documentation, ensuring that the navigation menus are user-friendly is vital. By default, the Autosummary extension generates menus that include the full path to each object, leading to lengthy menu items.
One effective way to simplify this is by changing the references from fullname to just name in the custom template files. By modifying these templates, you can shorten menu items to display only the object name, enhancing overall readability.
Thank you for reading! If you found this information useful, consider subscribing to my content to receive future articles directly in your inbox. If you enjoyed this article, feel free to show your appreciation with a few claps!