sphinx-remove-toctrees

1.0.0.post1 verified Fri May 01 auth: no python

A Sphinx extension that allows you to remove toctrees from certain pages to reduce documentation build size. Current version: 1.0.0.post1. Maintained by the ExecutableBooks project, infrequent releases.

pip install sphinx-remove-toctrees

Common errors

error KeyError: 'remove_toctrees_from' not in config ↓

cause Configuration option not defined in conf.py or misspelled.

fix

Add 'remove_toctrees_from = []' to conf.py even if empty, or check spelling.

error WARNING: toctree is missing from page, but referenced in ... ↓

cause Removing a toctree from a page that is included via another toctree may cause orphaned references.

fix

Ensure pages with removed toctrees are not listed as toctree entries elsewhere, or use Sphinx's 'orphan' directive.

error Extension 'sphinx_remove_toctrees' has no setup() function ↓

cause Wrong import or the package is not installed.

fix

Run 'pip install sphinx-remove-toctrees' and ensure conf.py has 'extensions = ['sphinx_remove_toctrees']'.

Warnings

gotcha The 'remove_toctrees_from' config value expects a list of document names (without .rst/.md extension) relative to source directory. Including extensions or full paths will silently fail. ↓

fix Use e.g. 'page_without_toctree' not 'source/page_without_toctree.rst'.

gotcha This extension removes the toctree directive from pages entirely, not just hiding it. Navigation may be affected if those pages are expected to display subpages. ↓

fix Only apply to pages where toctree is unnecessary (e.g., standalone content pages).

deprecated In version 0.0.3, the configuration option was renamed from 'remove_toctrees_from' (previously 'exclude_toctrees'). The old name may still work but is undocumented. ↓

fix Use 'remove_toctrees_from' in conf.py.

Imports

sphinx_remove_toctrees
```
import sphinx_remove_toctrees
```
No common import mistakes; extension added via conf.py entry point, not direct import.

Quickstart

Enable the extension and configure which pages to remove toctrees from via the 'remove_toctrees_from' list.

extensions = ['sphinx_remove_toctrees']
# exclude specific pages from having toctrees
remove_toctrees_from = ['page_to_remove.rst', 'another_page.rst']