Multi-version?

[brechtm]

This project's README mentions it is a multi-version documentation generator. However, the BTD docs adn the other examples linked to do not show multiple versions; neither project versions nor formats (PDF). Perhaps this is still on the to-do list?

[eine]

Hi @brechtm!

Thanks for bringing this topic, and I'm sorry about forgetting this issue...

This is actually half done and half unfinished. The theme is modified for properly defining some branch specific fields (such as the 'Edit me' links. At the same time, BTD generates a JSON, which is read by the conf script and added to the context: https://github.com/buildthedocs/btd/blob/master/doc/conf.py#L46-L49. See also https://github.com/buildthedocs/btd/blob/master/btd/__init__.py#L254-L279. Therefore, the plumbing for building multiple versions is ready. However:

In RTD, JavaScript code is injected in the theme by their backend, which picks metadata from their database. That's used for displaying the floating menu that links to multiple versions. When GitHub Pages or GitLab Pages is used instead, there is no such database. Conversely, all pages are static. As a result, it is challenging to show links to other versions. That is because adding a version would require all others to be rebuilt. That was the approach in the inial version of this project, written in shell scripts (see https://github.com/buildthedocs/btd/tree/master/shbtd). There, the user would provide a list of versions (tags/branches) and all of them would be built at once. That was not practical. Users would typically want to update one branch at a time.

Therefore, my view is to have each version built independently (as it is now) but uploaded to a subdir (instead of the root). Then, have a landing/root page, which links to the multiple versions. The landing page might be updated whenever a version is updated, or it could have some minimal JS for reading the list of versions from a JSON file.

Still, that would not allow to switch from an specific page in one version, to the same page in another version. That would necessarily require additional JS, because pages can exist in one version but not in others.

Moreover, this is related to linking to PDFs, ebooks and/or man pages, which can also built with Sphinx. In a prior version of the sphinx_btd_theme, a menu was added at the top, which allowed downloading those. In a later version, the landing page showed the links to those artifacts.

Overall, the main issue is that I'm not a frontend designer and I don't feel comfortable with JS or CSS. I could/can make some default template which works on some devices, but it will probably be broken on smartphones, etc. That's why the multi-version feature is not finished or documented yet.

On the other hand, after long time it seems that sphinx_rtd_theme might be reworked and updated (see readthedocs/sphinx_rtd_theme#1086). However, the technical debt is significant. Since sphinx_btd_theme is based on that, I think it's better to wait until their major release before rebasing.

Anyway, since the landing/root template is independent from the Sphinx theme, any contribution regarding the multi-version feature is very welcome!

[brechtm]

I've rolled my own solution for the rinohtype docs built on GitHub Actions and some custom Javascript. It doesn't require old versions of the documentation to be rebuilt. For those interested, you can find details in brechtm/rinohtype@1270802 and parent commits.