Sphinx Toolbox

4.1.2 · active · verified Mon Apr 13

sphinx-toolbox is a collection of handy tools and extensions designed to enhance Sphinx, the Python documentation generator. It provides various directives, roles, advanced autodoc features, and general tweaks to improve the Sphinx documentation experience. The library is currently at version 4.1.2 and maintains an active development cycle, releasing minor and patch versions frequently to support new Sphinx and Python versions.

Warnings

breaking In version 4.0.0, the `sphinx_toolbox.source` module no longer automatically enables the `sphinx_toolbox.github` extension. If you have `source_link_target` set to `'GitHub'`, you must manually add `'sphinx_toolbox.github'` to your `extensions` list in `conf.py`.
Fix: Add `'sphinx_toolbox.github'` to the `extensions` list in your `conf.py` if you rely on GitHub source links via `sphinx_toolbox.source`.
gotcha While the version cap for `sphinx-autodoc-typehints` was removed in `sphinx-toolbox` 3.1.0, some configuration options introduced in `sphinx-autodoc-typehints` after version 1.14.1 might not work as expected. This is because `sphinx-toolbox` customizes certain internal functions of `sphinx-autodoc-typehints`.
Fix: If encountering issues with `sphinx-autodoc-typehints` configuration, consider testing with `sphinx-autodoc-typehints` version 1.14.1 or earlier, or reviewing `sphinx-toolbox` documentation for known incompatibilities with newer `sphinx-autodoc-typehints` features.
gotcha Sphinx-toolbox frequently updates its compatibility with various Sphinx versions. Ensure that the installed `sphinx-toolbox` version is compatible with your Sphinx installation to avoid unexpected build errors or broken features. Refer to the changelog for specific Sphinx version support.
Fix: Always check the `sphinx-toolbox` changelog or documentation for compatible Sphinx versions when upgrading either library. Update `sphinx-toolbox` if you upgrade Sphinx, and vice-versa, to maintain compatibility.
gotcha When using the `sphinx_toolbox.source` extension, the `source_link_target` configuration option must be set to either `'GitHub'` or `'Sphinx'` (case-insensitive). Providing any other value will result in an `InvalidOptionError` during the Sphinx build.
Fix: Ensure `source_link_target` in `conf.py` is one of the valid string values: `'GitHub'` or `'Sphinx'`.

Install

pip install sphinx-toolbox Install latest version

Imports

sphinx_toolbox
```
# In conf.py
extensions = [
    'sphinx.ext.autodoc',
    'sphinx_toolbox',
    'sphinx_toolbox.more_autodoc' # Or specific sub-extensions
]
```
sphinx-toolbox components are typically enabled as Sphinx extensions in `conf.py` rather than imported directly as Python modules. Adding 'sphinx_toolbox' enables a set of default features, while 'sphinx_toolbox.more_autodoc' enables all enhanced autodoc features.

Quickstart

To quickly get started, install the library and then add 'sphinx_toolbox' and any desired sub-extensions (like 'sphinx_toolbox.more_autodoc') to the `extensions` list in your Sphinx project's `conf.py` file. This enables the enhanced features provided by the toolbox.

# conf.py

# Standard Sphinx extensions
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
]

# Add sphinx-toolbox extensions
extensions.extend([
    'sphinx_toolbox', # Enables core toolbox features
    'sphinx_toolbox.more_autodoc', # Enables all enhanced autodoc features
    # Or enable specific sub-extensions individually, e.g.:
    # 'sphinx_toolbox.collapse',
    # 'sphinx_toolbox.github',
    # 'sphinx_toolbox.installation',
])

# Project information
project = 'My Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1.0'

# Example of a sphinx-toolbox configuration option
# source_link_target = 'GitHub' # For sphinx_toolbox.source extension

view raw JSON →