Add ability to embed a readthedocs style version switcher in static sites

[samuel-emrys]

Context

It's often useful to have multiple versions of documentation, and to be able to switch between these easily. The readthedocs theme makes this easy by providing the structure and css to be able to embed a version switcher by providing a versions.html template, which results in the following:

I'm using sphinx-multiversion which provides the HTML context with which to populate this version switcher, however it seems as though it's not possible to inject this template anywhere into the sphinx-book-theme to get a similar result to what readthedocs provides in their template.

I notice that in your own documentation, you have an equivalent version switcher:

However, it doesn't seem to be possible to replicate this using the theme's options, currently.

Proposal

In this issue, I'm proposing adding the features necessary for a user to instantiate the version switcher as demonstrated in your documentation, on their own static website, without using readthedocs.

As far as I can tell, this would mean the addition of the following features:

• Ability to inject a template into the <div id="rtd-footer-container"> node (currently can only inject into the bd-sidebar__top or bd-sidebar__bottom nodes using existing theme options)
• Addition of the appropriate CSS for the rst-versions, rst-badge, shift-up, rst-current-version, rst-other-versions, rst-current-item CSS classes. What's missing seems to largely be contained within badge_only.css and readthedocs-doc-embed.css (not currently shipped with this theme).
• Addition of the appropriate javascript to handle interactivity with the version switcher. This seems to largely be contained within readthedocs-doc-embed.js (not currently shipped with this theme)

I've had limited success hacking my way through this by injecting the above template here: https://github.com/executablebooks/sphinx-book-theme/blob/ea8efeebaf4dd7b3bc3b1faeb373d2b919501abe/src/sphinx_book_theme/theme/sphinx_book_theme/layout.html#L46

And adding the aforementioned .css and .js files as static resources (in the _static folder). However, it hasn't been perfect and I'm still missing the interactivity so I assume the javascript isn't working correctly. Not being particularly familiar with sphinx templating or theming, I'm hoping that the way to get this to work will be relatively obvious to one of the maintainers.

Tasks and updates

No response

Related issues

449

https://github.com/pydata/pydata-sphinx-theme/issues/234 https://github.com/pydata/pydata-sphinx-theme/issues/647

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[billcxx]

I'm also looking for a solution to integrate the sphinx-multiversion with the book theme

[Cynerd]

For anyone looking for the integration with sphinx-multiversion. I put together template based on this theme and sphinx-multiversion version listing.

{% if versions %}
<nav class="bd-links bd-docs-nav">
    <div class="bd-toc-item navbar-nav">
        <ul class="nav bd-sidenav">
      <li class="toctree-l1 has-children">
        <p class="caption" aria-level="2" role="heading">
          <span type="button" class="caption-text">Version:  {{ current_version.name }}</span>
        </p>
        <input class="toctree-checkbox" id="version-checkbox" name="version-checkbox" type="checkbox"/>
        <label class="toctree-toggle" for="version-checkbox"><i class="fa-solid fa-chevron-down"></i></label>
        <ul>
          {%- for item in versions.branches %}
          <li class="toctree-l2 {% if item == current_version %}current{% endif %} "><a class="reference" href="{{item.url}}">{{item.name}}</a></li>
          {%- endfor %}
          {%- for item in versions.tags|reverse %}
          <li class="toctree-l2 {% if item == current_version %}current{% endif %} "><a class="reference" href="{{item.url}}">{{item.name}}</a></li>
          {%- endfor %}
        </ul>
      </li>
    </ul>
    </div>
</nav>
{% endif %}

It is not perfect but it might be a base for someone who might be willing to invest a bit of more time than me.