Sidebars from sphinx-multiversion

[riedgar-ms]

I'm trying to use sphinx-multiversion on our pydata-sphinx-theme docs, and I'm having trouble having the version sidebar appear. I've created the versioning.html sidebar file as mentioned in the multiversion documentation, and added the following to conf.py:

html_sidebars = {
    '*': ["versioning.html"],
}

However, I'm not seeing the sidebars appear. Does the pydata-sphinx-theme use this sidebar setting? The fact that the theme has left and right sidebars makes me wonder, but the documentation doesn't seem to mention any alternative setting.

If there is an alternative package for generating documentation for multiple versions of a repo which is better integrated with pydata-sphinx-theme, I'd be happy to switch too.

[choldgraf]

Ah I don't believe that it does. Here's the sidebar template: https://github.com/pandas-dev/pydata-sphinx-theme/blob/master/pydata_sphinx_theme/docs-sidebar.html

I think we'd need to add in some lines there about adding the extra HTML templates if desired.

[riedgar-ms]

Is there some other suggested way of building multiple versions and linking between them? I've seen some comments in the issues about enabling something like the ReadTheDocs version selector, but I'm not clear on how to make use of them.

[choldgraf]

hmmm, I don't know of another way to accomplish this unless the multiversion extension lets you insert a widget or button somewhere, but I think we should probably add support for the Sphinx sidebar extensions

[riedgar-ms]

sphinx-multiversion can generate an HTML <div> snippet as a file, if there's a way of inserting that onto every page within the pydata theme?

Otherwise, I can upgrade that snippet file into a landing page, and have users select from there.

[choldgraf]

I think you could define your own template in a _template folder that could work, if you knew the HTML to manually inject. Otherwise I think this should just be a feature added to the theme

[riedgar-ms]

The sphinx-multiversion documentation also contains a sample of putting a file with an HTML fragment which is expanded to contain appropriate links into the _templates directory.... how do I get that picked up by the pydata theme? Does it need to have a particular name?

[choldgraf]

I think it should just follow whatever is the normal practice for doing this in Sphinx. I believe the page is named layout.html in this theme but I haven't done this particular thing before so not sure exactly what to do

[riedgar-ms]

Hmmm, I've put a document called version.html_t in my _templates directory, with the following contents:

{% extends "pydata_sphinx_theme/layout.html" %}
{% block docs_toc %}
<h1>This is a version sidebar</h1>
{{ super() }}
{% endblock %}

However, nothing is appearing on the page. I can't even find it being referenced in the Sphinx log (with -vvv). I'm also temporarily running with plain sphinx-build in an effort to get anything injected.

[choldgraf]

I'm not sure what to tell you (and I'm about to go on paternity leave so probably won't be able to help out). Maybe @jorisvandenbossche has thoughts there.

[riedgar-ms]

Enjoy your leave.

@jorisvandenbossche , I did managed to figure out that I needed to call the file layout.html and have the following content:

{% extends "!pydata_sphinx_theme/layout.html" %}
{% block docs_navbar %}
{{ super() }}
{% if versions %}
<div class="container-xl">
<h4>{{ _('Versions') }}</h4>
<ul>
  {%- for item in versions %}
  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
  {%- endfor %}
</ul>
</div>
{% endif %}
{% endblock %}

(everything to do with versions comes from sphinx-multiversion. However, the layout is odd:

It appears that the extra <div> I'm injecting is going across the entire top of the content area, and not just into the sidebar. I have experimented with some of the other possible classes for the <div> but they are just breaking in various interesting ways.

[riedgar-ms]

Is there anything I can do to help add the hooks for customising the sidebar in the pydata theme? I have been playing around, trying to inject the HTML into the right place, but I can't seem to get it to appear correctly (which might just be due to my combined ignorance of how Sphinx manages these things, and how the CSS fits together).

[CAM-Gerlach]

Hey, we've done this downstream in spyder-ide/spyder-docs-sphinx-theme (check out our docs site for how it looks) and hope to upstream support here soon, at least the ability to inject your custom templates in the sidebar, and perhaps full support for the Sphinx-Multiversion dropdown without having to add bespoke support to each docs site. Stay tuned, and if you want a quick fix, check out spyder-ide#33 for how we added the hooks (not sure its the best way, but we iterated a few times on it).

[dalthviz]

Hi, yep as @CAM-Gerlach says we have worked on this for the Spyder docs (and we added some other stuff that maybe could be nice to get upstream too :) ). Particularly, these are a couple of ideas we thought about (we went with the first alternative but maybe is worthy to explore the second alternative too) to render the versions information and that you can see implemented in the PR linked by @CAM-Gerlach :

1. html_sidebars support:

Theme side

Change the docs-sidebar.html layout in the theme to add support for the html_sidebars option with something like this:

{%- if sidebars %}
       {%- for sidebartemplate in sidebars %}
              {%- include sidebartemplate %}
       {%- endfor %}
{%- endif %}

Your docs side

Add a template to manage the version to the _templates dir (the versioning.html described) and add the config for the sidebar widget:

html_sidebars = {
    '**': ["versioning.html"],
}

2. Add support for the sphinx-multiversion extension directly in the theme:

Theme side

Change the docs-sidebar.html layout to support directly the template for the versioning and add a validation to render the template something like:

{%- if versions %}
    {%- include "versioning.html" %}
{%- endif %}

Theme side/your docs side

Probably in this case a base versioning.html template should be added to the theme as a default way to render the versions (and if someone wants to change the way it shows they could overwrite the template by creating their own version and putting it in the _templates dir)

[CAM-Gerlach]

A middle ground between the two we also thought about that has most of the advantages of both is to simply host the versioning.html sidebar template (along with the supporting CSS and JS) in the theme instead of your downstream repo, so you'd just have to add it to html_sidebars as normal to enable it, or replace it with a template of your own wherever you like (rather than at one hardcoded path, overriding the original). If we added it to sidebars of theme.conf, it would automatically render if your docs were built with sphinx-multiversion without having to add it manually. This avoids the need to copy and maintain the relevant HTML, CSS and JS in every downstream docs repo (as does the second) while having the benefit of sidebar support and avoiding hardcoding the path and position of the template as in the second.

[riedgar-ms]

Hmmm.... I'm not keen on copying pydata-sphinx-theme into our repo. I've tried overriding docs-sidebar.html but I can't get the version info to appear.

[choldgraf]

Note that this theme now supports the Sphinx "sidebars" config:

html_sidebars = {
   "pagename": ["sidebar1.html", "sidebar2.html"]
}

It should now be possible to include any sidebars from other extensions 👍

[riedgar-ms]

I saw, and was able to do so, thanks!

[choldgraf]

wohoo! so I think we can close this now?

[riedgar-ms]

Yes

[choldgraf]

🎉