| Name | sphinx-remove-toctrees JSON |
| Version |
1.0.0.post1
JSON |
| download |
| home_page | None |
| Summary | Reduce your documentation build size by selectively removing toctrees from pages. |
| upload_time | 2024-03-22 11:00:03 |
| maintainer | None |
| docs_url | None |
| author | Executable Book Project |
| requires_python | >=3.9 |
| license | MIT License Copyright (c) 2018 Chris Holdgraf Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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`:
```console
$ pip install sphinx-remove-toctrees
```
activate it by adding it to your Sphinx extensions in `conf.py`:
```python
extensions.append("sphinx_remove_toctrees")
```
## Use
In `conf.py`, there is a top-level configuration key called `remove_from_toctrees` that allows you to specify the pages to remove from your sidebar.
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`:
```python
remove_from_toctrees = ["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`:
```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:
```python
remove_from_toctrees = ["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 `tocs` to ensure that files in your documentation are linked _somewhere_, and will raise warnings if it finds a file that is not in one of the `tocs`.
- Later in the build, Sphinx uses these `tocs` to build the HTML `toctree` with links to pages in your documentation. If there are many elements in `tocs`, 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-remove-toctrees",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Executable Book Project",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9a/50/e3153912d4382bb434b3679a42eb96966f8b741789004412d1ceecbeee30/sphinx_remove_toctrees-1.0.0.post1.tar.gz",
"platform": null,
"description": "# Remove toctrees from Sphinx pages\n\n\n\nImprove your Sphinx build time by selectively removing TocTree objects from pages.\nThis is useful if your documentation uses auto-generated API documentation, which\ngenerates **a lot** of stub pages.\n\nThis extension can be used to remove the sidebar links for just the pages you specify, speed up the build considerably.\n\n## Who is this for?\n\nThis package is for maintainers that use Sphinx and have really large API documentation (or for some other reason, have a ton of nested pages).\nIf 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.\nUse this theme to speed up your builds.\n\n## Install\n\nInstall the extension via `pip`:\n\n```console\n$ pip install sphinx-remove-toctrees\n```\n\nactivate it by adding it to your Sphinx extensions in `conf.py`:\n\n```python\nextensions.append(\"sphinx_remove_toctrees\")\n```\n\n## Use\n\nIn `conf.py`, there is a top-level configuration key called `remove_from_toctrees` that allows you to specify the pages to remove from your sidebar.\nProvide a list of `glob`-like paths **relative to your documentation root**.\nEach entry should match to pages that should be removed from the sidebar.\n\nFor example, the following configuration will remove all pages from the folder `api/generated`, and the specific page `subfolder/page_two.rst`:\n\n```python\nremove_from_toctrees = [\"api/generated/*\", \"subfolder/page_two.rst\"]\n```\n\nThis is particularly useful in combination with the `autosummary` directive, which tends to generate a ton of stub-pages that slows things down.\n\nIf you have the following autosummary directive in a page at `myfolder/page1.rst`:\n\n```rst\n.. autosummary: datetime.datetime\n :toctree: api_gen\n```\n\nThis will generate stub-pages in a `myfolder/api_gen/` folder.\nTo remove each of these pages from your sidebar, you would configure this extension like so:\n\n```python\nremove_from_toctrees = [\"myfolder/api_gen/*\"]\n```\n\n\n## Try it with this documentation\n\nThis extension doesn't have a hosted documentation page, but there is one in the `docs/` folder of this repository.\nYou can use that folder to preview this extension in action.\n\n\n## How this works\n\nSphinx keeps track of `toctree` objects to represent the structure of your documentation.\nThese exist in the Sphinx environment object, at `env.tocs`.\nThere are two places in the build where this is relevant here:\n\n- Early in the build, Sphinx uses these `tocs` to ensure that files in your documentation are linked _somewhere_, and will raise warnings if it finds a file that is not in one of the `tocs`.\n- Later in the build, Sphinx uses these `tocs` to build the HTML `toctree` with links to pages in your documentation. If there are many elements in `tocs`, it will take a long time to resolve all of these links!\n\nThis extension runs *after* the first step, but *before* the second step.\nIt 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.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2018 Chris Holdgraf Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Reduce your documentation build size by selectively removing toctrees from pages.",
"version": "1.0.0.post1",
"project_urls": {
"Homepage": "https://github.com/executablebooks/sphinx-remove-toctrees"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bc1959dadac9ee5e8fa32b0d735b5488a569de36892a54e0b9927bea2b22f605",
"md5": "c501904fdd1893af1a0f2f8fcb2096aa",
"sha256": "22a96579d7899cc034de194195916717a54a122cc101f16ec79c996fe0baa2be"
},
"downloads": -1,
"filename": "sphinx_remove_toctrees-1.0.0.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c501904fdd1893af1a0f2f8fcb2096aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 5200,
"upload_time": "2024-03-22T11:00:01",
"upload_time_iso_8601": "2024-03-22T11:00:01.507381Z",
"url": "https://files.pythonhosted.org/packages/bc/19/59dadac9ee5e8fa32b0d735b5488a569de36892a54e0b9927bea2b22f605/sphinx_remove_toctrees-1.0.0.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9a50e3153912d4382bb434b3679a42eb96966f8b741789004412d1ceecbeee30",
"md5": "a348043f08b63f73a767206e2ced0c9d",
"sha256": "4808d1edf151c06eff6d2c3922ec7ebc9fd3aa1762de1b2e1674a37f5ac9ce2d"
},
"downloads": -1,
"filename": "sphinx_remove_toctrees-1.0.0.post1.tar.gz",
"has_sig": false,
"md5_digest": "a348043f08b63f73a767206e2ced0c9d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 8473,
"upload_time": "2024-03-22T11:00:03",
"upload_time_iso_8601": "2024-03-22T11:00:03.727860Z",
"url": "https://files.pythonhosted.org/packages/9a/50/e3153912d4382bb434b3679a42eb96966f8b741789004412d1ceecbeee30/sphinx_remove_toctrees-1.0.0.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-22 11:00:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "executablebooks",
"github_project": "sphinx-remove-toctrees",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-remove-toctrees"
}
