Greetings, wonderful theme devs! I'm currently transitioning @beartype's embarrassingly monolithic README.rst documentation ^{...which is so large it's actually breaking pip-based installation for a subset of users} onto ReadTheDocs, backed by this wonderful theme.

Prior theme versions allowed the left sidebar to be "trivially" customized via a _templates/sidebar-nav-bs.html template with horrifying boilerplate I don't pretend to understand like:

<nav class="bd-links d-none d-md-block" id="bd-docs-nav" aria-label="{{ _('Main navigation') }}">
  <div class="bd-toc-item active">
    {{ generate_nav_html("sidebar",
                         startdepth=0,
                         maxdepth=theme_navigation_depth|int,
                         show_nav_level=theme_show_nav_level|int,
                         collapse=theme_collapse_navigation|tobool,
                         includehidden=True,
                         titles_only=True) }}
  </div>
</nav>

Current theme versions instead centralize similar logic inside the main layout.html template. This mostly makes sense, as doing so avoids displaying an empty left sidebar. But this also appears to prevent full-blown customization of the left sidebar (like above), which sorta makes less sense. Specifically, layout.html is now prefaced by this Jinja madness cleverness:

{# Create the sidebar links HTML here to re-use in a few places #}
{# If we have no sidebar links, pop the links component from the sidebar list #}
{%- set sidebar_nav_html = generate_toctree_html("sidebar",
    show_nav_level=theme_show_nav_level|int,
    maxdepth=theme_navigation_depth|int,
    collapse=theme_collapse_navigation|tobool,
    includehidden=True,
    titles_only=True)
-%}
{% if sidebar_nav_html | length == 0 %}
{% set sidebars = sidebars | reject("in", "sidebar-nav-bs.html") | list %}
{% endif %}

My Jinja is weak. Still, I'm pretty sure that precludes meaningful user-driven overrides of the sidebar_nav_html configuration setting – unless I'm missing something, which I probably am. See: "My Jinja is weak."

Superficially, users can (of course) attempt to override sidebar_nav_html by adding a downstream _templates/layout.html file resembling:

{%- extends "!layout.html" %}
{%- set sidebar_nav_html = generate_toctree_html("sidebar",
    startdepth=0,
    show_nav_level=theme_show_nav_level|int,
    maxdepth=theme_navigation_depth|int,
    collapse=theme_collapse_navigation|tobool,
    includehidden=True,
    titles_only=True)
-%}

Pragmatically, that's just a noop. This theme's layout.html already detected sidebar_nav_html as being empty and then forcefully removed sidebar-nav-bs.html from the sidebars list. That behaviour is no longer amenable to user customization. Is that right? If so...

What I Am Begging of You Here is...

A new theme-specific configuration global allowing users to intervene in this process... somehow.

In @beartype's case, I'd just like to display the full TOC tree in the left sidebar by passing startdepth=0 to the generate_toctree_html() call. This appears to be a common concern (e.g., at #90, #221, and presumably elsewhere). Tragically, the internal structure of this theme changed so fundamentally that prior workarounds no longer apply. Thankfully, a permanent fix avoiding fragile external workarounds that were guaranteed to fail (and then did) should be trivial!

Let's add a new theme-specific theme_navigation_start_depth global for parity with existing globals. In theory, adding this single line to layout.html should more-or-less suffice: e.g.,

{# Create the sidebar links HTML here to re-use in a few places #}
{# If we have no sidebar links, pop the links component from the sidebar list #}
{%- set sidebar_nav_html = generate_toctree_html("sidebar",
    startdepth=theme_navigation_start_depth|int,  # <-- MAGIC ONE-LINER IS MAGICAL.
    show_nav_level=theme_show_nav_level|int,
    maxdepth=theme_navigation_depth|int,
    collapse=theme_collapse_navigation|tobool,
    includehidden=True,
    titles_only=True)
-%}
{% if sidebar_nav_html | length == 0 %}
{% set sidebars = sidebars | reject("in", "sidebar-nav-bs.html") | list %}
{% endif %}

If everyone's amenable, I'd be happy to submit a working PR with working tests (and possibly even documentation – but let us not get too optimistic here) at some point. Until then, I've very reluctantly pinned @beartype to a prior version of this theme. (The RTD flyout disappearing under recent versions also made this decision easier than I would have liked. I sigh.)

Thanks again for all the wondrous theming, everyone. PyData FTW forever! 👍