diff --git a/docs/customisation/index.md b/docs/customisation/index.md index 61edf0f56..5204289f7 100644 --- a/docs/customisation/index.md +++ b/docs/customisation/index.md @@ -16,6 +16,7 @@ footer landing-page sidebar sidebar-title +sidebar-depth toc injecting ``` diff --git a/docs/customisation/sidebar-depth.md b/docs/customisation/sidebar-depth.md new file mode 100644 index 000000000..57a64277b --- /dev/null +++ b/docs/customisation/sidebar-depth.md @@ -0,0 +1,37 @@ +# Changing sidebar depth + +By default, Furo includes your full site in the left sidebar's table of contents. This is intentional to have a good user experience: + +- users can easily navigate your whole site with fewer clicks, and +- they can easily see where they are in the site hierarchy. + +However, for large projects, including the full site in the sidebar can result in two issues: + +1. slow Sphinx build performance, and +2. large HTML page sizes, which slows down your site's initial load. + +For example, large sidebars can be a problem when using [Sphinx's autosummary](https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html) with a large API. + +You can limit the depth of the left sidebar by setting `navigation_depth` in `html_theme_options` in `conf.py` to a number like `2` or `3`. It defaults to `-1`. + +```python +html_theme_options = { + "navigation_depth": 4, +} +``` + +However, setting `navigation_depth` lower can result in a worse user experience navigating your site. Only set `navigation_depth` if you are having issues with Sphinx build times and/or the HTML page size. Experiment to find a number that balances those problems with keeping a good navigation experience. + +Before changing `navigation_depth`, consider if you can reorganize your site to reduce the number of HTML pages. For example, with `autosummary`, consider changing its templates so that each function does not get a dedicated HTML page. + +## Tip: consider dynamically setting `navigation_depth` + +You can dynamically set the `navigation_depth` via an environment variable. That allows you to use a deeper `navigation_depth` like `-1` or `4` for your production builds, while using a lower number like `1` or `2` in development builds (e.g. CI) to speed up Sphinx. + +For example: + +```python +import os + +html_theme_options = {"navigation_depth": os.getenv("NAVIGATION_DEPTH", -1)} +``` diff --git a/src/furo/__init__.py b/src/furo/__init__.py index 97a7cfbc0..762fffc59 100644 --- a/src/furo/__init__.py +++ b/src/furo/__init__.py @@ -10,6 +10,7 @@ from typing import Any, Dict, Iterator, List, Optional import sphinx.application +import sphinx.config from docutils import nodes from pygments.formatters import HtmlFormatter from pygments.style import Style @@ -112,14 +113,16 @@ def get_colors_for_codeblocks( ) -def _compute_navigation_tree(context: Dict[str, Any]) -> str: +def _compute_navigation_tree( + config: sphinx.config.Config, context: Dict[str, Any] +) -> str: # The navigation tree, generated from the sphinx-provided ToC tree. if "toctree" in context: toctree = context["toctree"] toctree_html = toctree( collapse=False, titles_only=True, - maxdepth=-1, + maxdepth=config.html_theme_options.get("navigation_depth", -1), includehidden=True, ) else: @@ -196,7 +199,7 @@ def _html_page_context( context["furo_version"] = __version__ # Values computed from page-level context. - context["furo_navigation_tree"] = _compute_navigation_tree(context) + context["furo_navigation_tree"] = _compute_navigation_tree(app.config, context) context["furo_hide_toc"] = _compute_hide_toc( context, builder=app.builder, docname=pagename ) diff --git a/src/furo/theme/furo/theme.conf b/src/furo/theme/furo/theme.conf index dd3606d6d..c2b0920b0 100644 --- a/src/furo/theme/furo/theme.conf +++ b/src/furo/theme/furo/theme.conf @@ -19,6 +19,7 @@ dark_css_variables = dark_logo = light_css_variables = light_logo = +navigation_depth = sidebar_hide_name = footer_icons = top_of_page_button = edit