[ENH, DOC] Allow setting the navbar_max_depth and collapse_navbar (…

…#605)

Co-authored-by: Chris Holdgraf <choldgraf@berkeley.edu>

docs/reference.md

@@ -42,7 +42,16 @@ These are **in addition to** all of the {external:doc}`options available in the
   - Whether to put the home page in the Navigation Bar (at the top). See [](sidebar-primary:home-page).
 * - `show_navbar_depth`
   - int
-  - Show children in the navigation bar down to the depth listed here. See [](sidebar:navbar-depth).
+  - Show children in the navigation bar down to the depth listed here. See [](sidebar:show-navbar-depth).
+* - `max_navbar_depth`
+  - int
+  - The maximum number of levels to show in the navbar. See [](sidebar:max-navbar-depth). (4 is default)
+* - `collapse_navbar`
+  - bool
+  - Whether to collapse the navbar, stopping the tree from being expanded. See [](sidebar:max-navbar-depth), (False is default)
+* - `extra_navbar`
+  - str
+  - Extra HTML to add below the sidebar footer. See [](custom-footer).
 * - `extra_footer`
   - str
   - Extra HTML to add in the footer of each page.

docs/sections/sidebar-primary.md

@@ -58,7 +58,7 @@ html_theme_options = {
 }
 ```
 
-(sidebar:navbar-depth)=
+(sidebar:show-navbar-depth)=
 ## Control the depth of the left sidebar lists to expand
 
 You can control the level of toc items in the left sidebar to remain expanded,
@@ -73,3 +73,36 @@ html_theme_options = {
 ```
 
 The default value is `1`, which shows only top-level sections of the documentation (and is used in this documentation).
+
+(sidebar:max-navbar-depth)=
+
+## Control the maximum depth of the left sidebar lists
+
+You can control the level of toc items included in the left sidebar,
+using the following configuration in `conf.py`:
+
+```python
+html_theme_options = {
+    ...
+    "max_navbar_depth": <level>,
+    ...
+}
+```
+
+The default value is `4`.
+
+(sidebar:collapse-navbar)=
+## Turn off expandable left sidebar lists
+
+You can turn off the sidebar expanding,
+using the following configuration in `conf.py`:
+
+```python
+html_theme_options = {
+    ...
+    "collapse_navbar": True,
+    ...
+}
+```
+
+The default value is `False`, which allows the navbar to be expanded.

src/sphinx_book_theme/theme/sphinx_book_theme/components/sbt-sidebar-nav.html

@@ -15,10 +15,10 @@
         {{- generate_toctree_html(
             startdepth=0,
             kind="sidebar",
-            maxdepth=4,
-            collapse=False,
+            maxdepth=theme_max_navbar_depth|int,
+            collapse=theme_collapse_navbar|tobool,
             includehidden=True,
             titles_only=True,
-            show_nav_level=theme_show_navbar_depth) }}
+            show_nav_level=theme_show_navbar_depth|int) }}
     </div>
 </nav>

src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf

@@ -39,6 +39,8 @@ navbar_persistent =
 # Primary sidebar behavior
 home_page_in_toc = False
 show_navbar_depth = 1
+max_navbar_depth = 4
+collapse_navbar = False
 
 # Footer at the bottom of the content
 extra_footer =