Add navigation_depth to html_theme_options

docs/customisation/index.md

@@ -16,6 +16,7 @@ footer
 landing-page
 sidebar
 sidebar-title
+sidebar-depth
 toc
 injecting
 ```

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)}
+```

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
     )

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