{"id":5496,"library":"sphinx-toolbox","title":"Sphinx Toolbox","description":"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.","status":"active","version":"4.1.2","language":"en","source_language":"en","source_url":"https://github.com/sphinx-toolbox/sphinx-toolbox","tags":["sphinx","documentation","extension","autodoc"],"install":[{"cmd":"pip install sphinx-toolbox","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for all functionality. Compatibility with specific Sphinx versions is actively maintained and frequently updated.","package":"Sphinx","optional":false},{"reason":"Customized by sphinx-toolbox for enhanced type hint documentation; configuration options from versions > 1.14.1 might not function as expected.","package":"sphinx-autodoc-typehints","optional":true}],"imports":[{"note":"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.","wrong":"import sphinx_toolbox.some_feature","symbol":"sphinx_toolbox","correct":"# In conf.py\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx_toolbox',\n    'sphinx_toolbox.more_autodoc' # Or specific sub-extensions\n]"}],"quickstart":{"code":"# conf.py\n\n# Standard Sphinx extensions\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinx.ext.viewcode',\n]\n\n# Add sphinx-toolbox extensions\nextensions.extend([\n    'sphinx_toolbox', # Enables core toolbox features\n    'sphinx_toolbox.more_autodoc', # Enables all enhanced autodoc features\n    # Or enable specific sub-extensions individually, e.g.:\n    # 'sphinx_toolbox.collapse',\n    # 'sphinx_toolbox.github',\n    # 'sphinx_toolbox.installation',\n])\n\n# Project information\nproject = 'My Project'\ncopyright = '2026, Your Name'\nauthor = 'Your Name'\nrelease = '0.1.0'\n\n# Example of a sphinx-toolbox configuration option\n# source_link_target = 'GitHub' # For sphinx_toolbox.source extension\n","lang":"python","description":"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."},"warnings":[{"fix":"Add `'sphinx_toolbox.github'` to the `extensions` list in your `conf.py` if you rely on GitHub source links via `sphinx_toolbox.source`.","message":"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`.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=3.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `source_link_target` in `conf.py` is one of the valid string values: `'GitHub'` or `'Sphinx'`.","message":"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.","severity":"gotcha","affected_versions":"All versions with `sphinx_toolbox.source`"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}