Remove toctrees from Sphinx pages
Improve your Sphinx build time by selectively removing TocTree objects from pages. This is useful if your documentation uses auto-generated API documentation, which generates a lot of stub pages
This extension can be used to remove the sidebar links for just the pages you specify, speed up the build considerably.
Who is this for?
This package is for maintainers that use Sphinx and have really large API documentation (or for some other reason, have a ton of nested pages). If you use a Sphinx theme that contains the entire Table of Contents on every page (e.g., any theme that has "collapsable" sidebar sections), this will slow things down considerably. Use this theme to speed up your builds.
Install
Install the extension via pip:
$ pip install git+https://github.com/executablebooks/sphinx-remove-toctree
and activate it by adding it to your Sphinx conf.py file:
extensions = ["sphinx_remove_toctree"]
Use
In conf.py, provide a list of glob-like paths relative to your documentation root. Each entry should match to pages that should be removed from the sidebar.
For example, the following configuration will remove all pages from the folder api/generated, and the specific page subfolder/page_two.rst:
remove_toctrees_from = ["api/generated/*", "subfolder/page_two.rst"]
This is particularly useful in combination with the autosummary directive, which tends to generate a ton of stub-pages that slows things down.
If you have the following autosummary directive in a page at myfolder/page1.rst:
.. autosummary: datetime.datetime
:toctree: api_gen
This will generate stub-pages in a myfolder/api_gen/ folder. To remove each of these pages from your sidebar, you would configure this extension like so:
remove_toctrees_from = ["myfolder/api_gen/*"]
Try it with this documentation
This extension doesn't have a hosted documentation page, but there is one in the docs/ folder of this repository. You can use that folder to preview this extension in action.
How this works
Sphinx keeps track of toctree objects to represent the structure of your documentation. These exist in the Sphinx environment object, at env.tocs. There are two places in the build where this is relevant here:
- Early in the build, Sphinx uses these
tocsto ensure that files in your documentation are linked somewhere, and will raise warnings if it finds a file that is not in one of thetocs. - Later in the build, Sphinx uses these
tocsto build the HTMLtoctreewith links to pages in your documentation. If there are many elements intocs, it will take a long time to resolve all of these links!
This extension runs after the first step, but before the second step. It removes all the toctree objects that you specify, so that no warnings are raised about missing files, but they are removed from the sidebar and don't slow down your build.
584 Nov 16, 2022
166 Dec 29, 2022
118 Dec 31, 2022
71 Dec 26, 2022
2 Dec 26, 2022
8 Dec 15, 2022
4 Nov 22, 2022
6 Dec 22, 2022
266 Dec 13, 2022
16 Jul 21, 2022
14 Nov 07, 2022
1 Oct 22, 2021
2 Feb 14, 2022
25.5k Dec 29, 2022
6 Jun 10, 2022
1 Jan 14, 2022
10 Oct 06, 2022
361 Nov 16, 2022
6 Oct 02, 2022
1 Jan 19, 2022
9 Oct 12, 2022
1 Mar 01, 2022
15 Dec 06, 2022
3 Jun 19, 2022
3 May 03, 2022
3.8k Dec 30, 2022
64 Sep 18, 2022
3 Sep 21, 2022