Sphinx External ToC is a Sphinx extension that enables a top-down approach to defining the documentation's site-map (Table of Contents) using a single YAML file, typically `_toc.yml`. This contrasts with Sphinx's default bottom-up `toctree` directives spread across multiple reStructuredText files. The library is currently at version 1.1.0 and maintains an active release cadence, providing new features and bug fixes.
pip install sphinx-external-tocVerified import paths — ran on the pinned version, not inferred.
To quickly set up `sphinx-external-toc`, first add `sphinx_external_toc` to your `extensions` list in `conf.py`. Then, create a `_toc.yml` file in your source directory to define your documentation structure. This YAML file replaces the need for `.. toctree::` directives within your ReStructuredText or Markdown files. The `external_toc_path`, `use_multitoc_numbering`, and `external_toc_exclude_missing` options provide granular control over the ToC generation.
Upgrade your Python environment to 3.9 or newer. Ensure `requires_python='>=3.9'` is met.
Ensure `sphinx-multitoc-numbering` is installed alongside `sphinx-external-toc` (e.g., `pip install sphinx-external-toc sphinx-multitoc-numbering`).
After modifying `_toc.yml`, clear your Sphinx build cache by deleting the `_build` directory (or using `make clean` if a Makefile is present) before rebuilding your documentation.
To suppress this warning for documents intentionally excluded from the ToC, set `external_toc_exclude_missing = True` in your `conf.py`, or add `:orphan:` metadata to the top of each unlisted document file.
Always check the `sphinx-external-toc` documentation and release notes for tested Sphinx versions. When encountering unexpected behavior, try updating `sphinx-external-toc` to its latest version, or pin its version to one known to be compatible with your Sphinx installation.