version selector working? about sphinx-immaterial HOT 6 CLOSED

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:

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

from sphinx-immaterial.

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.

from sphinx-immaterial.

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.

from sphinx-immaterial.

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?

from sphinx-immaterial.

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.

from sphinx-immaterial.

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.

from sphinx-immaterial.