{"id":8669,"library":"sphinx-external-toc","title":"Sphinx External ToC","description":"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.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/sphinx-external-toc","tags":["sphinx","documentation","yaml","table-of-contents","jupyterbook"],"install":[{"cmd":"pip install sphinx-external-toc","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core documentation generator this extension integrates with.","package":"sphinx","optional":false},{"reason":"Required for parsing the `_toc.yml` file.","package":"pyyaml","optional":false},{"reason":"Provides advanced section numbering capabilities integrated with the external ToC.","package":"sphinx-multitoc-numbering","optional":false},{"reason":"Used for the `sphinx-etoc` command-line interface.","package":"click","optional":false}],"imports":[{"note":"The extension is enabled by adding its module name to the 'extensions' list in conf.py.","symbol":"sphinx_external_toc","correct":"extensions = [\n    'sphinx_external_toc',\n    # Other extensions...\n]"}],"quickstart":{"code":"# conf.py (in your Sphinx project's source directory)\nimport os\n\nproject = 'My Docs'\ncopyright = '2026, My Name'\nextensions = [\n    'sphinx_external_toc',\n    'myst_parser' # Example: if using Markdown\n]\n\n# Optional: Configure the external ToC\nexternal_toc_path = '_toc.yml' # Default: '_toc.yml'\nuse_multitoc_numbering = True # Default: True, enables numbered sections\nexternal_toc_exclude_missing = True # Default: False, prevents warnings for files not in ToC\n\n# --- Example _toc.yml (in your Sphinx project's source directory) ---\n# root: index\n# chapters:\n#   - file: intro\n#   - file: part1\n#     sections:\n#       - file: part1/chapter1\n#       - file: part1/chapter2\n#   - file: tutorial\n#   - url: https://example.com\n#     title: External Link\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer. Ensure `requires_python='>=3.9'` is met.","message":"Version 0.3.0 dropped support for Python 3.6. Projects using older Python versions must upgrade their environment to Python 3.7+ (or 3.9+ for current versions).","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Ensure `sphinx-multitoc-numbering` is installed alongside `sphinx-external-toc` (e.g., `pip install sphinx-external-toc sphinx-multitoc-numbering`).","message":"As of v1.0.0, `sphinx-external-toc` explicitly requires `sphinx-multitoc-numbering`. Older installations that do not have this dependency might fail after upgrade.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"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.","message":"Changes to the `_toc.yml` file, especially the `root` entry, may not always be reflected in the Sphinx build output unless the build cache is cleared.","severity":"gotcha","affected_versions":"All versions"},{"fix":"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.","message":"By default, Sphinx emits a 'WARNING: document isn't included in any toctree' for files not explicitly listed in your `_toc.yml`. While `sphinx-external-toc` manages the main ToC, explicitly unlisted files will still trigger this warning.","severity":"gotcha","affected_versions":"All versions"},{"fix":"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.","message":"Version compatibility between `sphinx-external-toc` and Sphinx itself can be a source of issues. For example, v0.3.1 explicitly added support for Sphinx 5. Newer Sphinx versions might introduce incompatibilities with older `sphinx-external-toc` releases.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Either include the document in your `_toc.yml`, add `:orphan:` metadata at the top of the document, or set `external_toc_exclude_missing = True` in your `conf.py`.","cause":"A documentation file exists in the source directory but is not referenced in the `_toc.yml` file, and `external_toc_exclude_missing` is not set to `True`.","error":"WARNING: document isn't included in any toctree"},{"fix":"Carefully review your `_toc.yml` file for proper YAML syntax. Use a YAML linter or validator to identify and correct structural issues. Pay close attention to indentation and key-value pair formatting.","cause":"The `_toc.yml` file contains syntax errors, such as incorrect indentation, missing colons, or invalid YAML structure.","error":"YAMLError: while parsing a block mapping"},{"fix":"Verify that the file specified under `root:` in `_toc.yml` exists and that its path is correct. Remember that paths in `_toc.yml` are relative to the source directory and do not include file extensions.","cause":"The file specified as `root` in your `_toc.yml` does not exist or its path is incorrect relative to your Sphinx source directory.","error":"The root document 'your_root_doc' was not found."}]}