sphinx-remove-toctrees

What it is and what it does

sphinx-remove-toctrees is a Sphinx extension that speeds up documentation builds by removing toctree objects from pages you specify. It works by intercepting Sphinx's build process after the initial validation phase but before HTML rendering, selectively deleting toctree entries that match glob-like patterns you configure in conf.py. This is most useful when your documentation uses autosummary to generate many stub pages—each one adds overhead to the build, especially in themes that render the entire table of contents on every page.

You configure it by adding a list of glob patterns to a `remove_from_toctrees` key in conf.py, specifying which pages should be removed from the sidebar. The extension ensures no warnings are raised about missing files while still removing them from the rendered navigation, avoiding the link-resolution overhead that slows large builds.

Use it for:

• Speed up Sphinx builds for projects with auto-generated API documentation using autosummary
• Remove stub pages from sidebar navigation without triggering missing-file warnings
• Optimize documentation rendering for themes with collapsible sidebar sections
• Reduce build time for large nested documentation hierarchies
• Selectively hide generated API pages from table of contents while keeping them accessible

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that selectively removes toctree objects from specified pages to reduce documentation build time, particularly for projects with large auto-generated API documentation.

Yes, if you maintain Sphinx documentation with large auto-generated API sections and experience slow builds. The extension is straightforward to configure, has no complex dependencies, and solves a specific performance problem. The dormant maintenance status is acceptable for a focused, stable tool—no active vulnerabilities and it supports current Python versions.

Install

sphinx-remove-toctrees on PyPI

pip install sphinx-remove-toctrees

uv add sphinx-remove-toctrees

poetry add sphinx-remove-toctrees

Installing sphinx-remove-toctrees

Before you install

Low friction: pure Python wheel with only sphinx as a runtime dependency. Maintenance is dormant—last release was 875 days ago, though the repository remains active and unarchived.

License in practice

MIT License permits unrestricted use, modification, and distribution with minimal restrictions, making it safe for both open-source and commercial projects.

Quickstart

pip install sphinx-remove-toctrees

In conf.py:
extensions.append("sphinx_remove_toctrees")
remove_from_toctrees = ["api/generated/*", "subfolder/page_two.rst"]

Verify before relying

• Performance improvement magnitude for typical documentation projects with large API docs
• Compatibility with specific Sphinx themes beyond those mentioned in the description

Package facts

Evidence: sphinx_remove_toctrees-1.0.0.post1-py3-none-any.whl

Tags

More Sphinx packages