version selector working?

[2bndy5]

I recently tried the version selector as the docs for this theme instruct, but it didn't work; the JSON file option nor the conf.py dict option made any difference or triggered any unusual build-time output. I know @jbms noted some changes to the version selector dopdown in his initial PR to the sphinx-material theme's repo

I changed the versions.json format to match the "mike" format supported by mkdocs-material.

So, I tried a json in the form that the mike plugin expects: still no joy.

At this point I think its just broken from a change in the HTML template's context variables. However, I'm actually having trouble finding the section of the template that integrates the version selector dropdown. I see the word "version" mentioned in the bottom of base.html about translations, but I have a feeling the mkdocs-material theme supports the mike plugin via added JS (which is where my expertise stops).

On a related note, I think I found the Sphinx alternative to the mkdocs' mike plugin: sphinxcontrib-versioning. It seems that this extension is the key ingredient to versioned docs on RTD as most of the sphinx themes' support it via the extension's html template API.

---

My initial intention was to try and have a doxygen rendered version and a sphinx/breathe rendered version of a project's docs I'm working on.

[jbms]

Yes, looks like the documentation for the version selector needs to be updated as well.

One the drawbacks to how both readthedocs versions work, and also how I believe sphinxcontrib-versioning works, is that the list of versions is hard coded into the generated HTML files of each version. Consequently, every time you add a new version, you have to rebuild the docs for every previous version, which poses a number of problems:

• If you have e.g. 100 versions, in order to add 1 more version you have to rebuild the docs 100 times.
• Old versions of your docs may no longer build with new versions of Python, new versions of other system dependencies, etc. (when using autodoc/autosummary with C extensions, you also have to actually build your package to build the docs).

In contrast, docs.python.org, the mkdocs "mike" plugin, and this theme use a different approach, where the version menu is generated dynamically via JavaScript. That allows you to modify the list of versions without rebuilding the documentation.

As far as the specifics regarding version selector for this theme:

There is no HTML template for versions, because versions are injected from the javascript code instead:

sphinx-immaterial/src/assets/javascripts/bundle.ts

Line 108 in 6267f13

setupVersionSelector()

sphinx-immaterial/src/assets/javascripts/integrations/version/index.ts

Line 36 in 6267f13

export function setupVersionSelector(): void {

You can add a version selector by adding the following to html_theme_options:

    "version_dropdown": True,
    "version_info": [
        {"version": "2.0", "title": "2.0", "aliases": ["latest"]},
        {"version": "1.0", "title": "1.0", "aliases": []},
    ],

If it isn't a relative path, you can make "version" a full URL.

In this example I have specified the list of versions inline in the config, which is similar to how readthedocs or sphinxcontrib-versioning would do it -- but that is just for demonstration purposes.

Instead of "version_info", you can instead specify "version_json": "versions.json" or similar. That option only works if your docs are served from a webserver (does not work if you use file:// url) and in that case the "version_json" file is resolved relative to the parent directory of the directory that your documentation is served from. So for example, you should have:

/versions.json
/1.0/index.html
/2.0/index.html

[2bndy5]

The last tidbit seems a worthy addition to the docs.

It's almost been a week since I tried the version selector feature, but I think I tried all avenues (version_json and version_info with the expected mike syntax) with no joy. I didn't specify an alias field though, may be that will change something.

Have you been able to ever use the version selector dropdown successfully? I assume the version_dropdown_text is a relic from sphinx-material theme's docs.

[jbms]

As I was writing the message above I tried it out and it did work. The "aliases" member is required, though it may be an empty list --- if it is missing you get an error in the JavaScript console. That may have been a limitation I introduced with my own modifications to the javascript, not sure.

[2bndy5]

the "version_json" file is resolved relative to the parent directory of the directory that your documentation is served from

This is a little confusing. I think what you're saying is that the versions.json file needs to be somehow copied into the _build directory (or the parent dir of whatever the user specifies as the builder's output). If so, then how should I document this? Would it require the user to also specify html_extra_path option in conf.py?

[jbms]

If the user has in their documentation source directory:

index.rst
something.rst
conf.py
...

Then the build output will have:

index.html
something.html
...

The user should then deploy this to their webserver as:

1.0/
  index.html
  something.html
  ...
2.0/
  index.html
  something.html
  ...
versions.json

The versions.json file is in the parent directory that contains all of the versions. The user needs to set up some mechanism for updating it when they deploy a new version. It doesn't make sense to ask sphinx to copy versions.json since Sphinx is just responsible for building the documentation for a single version, and versions.json goes outside the build tree of any single version, and the user needs to create a mechanism for generating it.

[2bndy5]

Good notes. I'm adding them to the revisions I'm working on. I'll be using the version selector to demonstrate switching from gh-pages to RTD (& vice-versa) in conf.py.