Add version selection option for library version.

[rheitjoh]

The Gradle library allows for selecting which version of Gradle you use and then shows the right documentation for that version. Once we have more than just version 1.0.0, it would be nice to offer a similar functionality for our documentation page.

Since we have multiple projects in our documentation, it would probably make sense to bundle up specific version of each library in a bigger "all of upb.crypto" version, similar to how Math 1.0.0, Craco 1.0.0, etc. are designed to work together. Then the selection would just differentiate between these bundles.

[feidens]

Any ideas how to handle this with our github.io site?

[rheitjoh]

My initial idea was to just have a different URL for each different version similar to how Gradle does it.
So instead of reaching the installation instructions at https://upbcuk.github.io/getting-started/installation.html like at the moment, you would reach the current installation instructions at https://upbcuk.github.io/current/getting-started/installation.html. An older version could then be reached at, for example, https://upbcuk.github.io/1.1.0/getting-started/installation.html.

As to how to realize this technically, a simple way would be to just maintain a copy of the docs for each version, i.e. we would have folders 1.1.0 and current that contain the docs for that version. Whenever we publish a new version of our library bundle, we move the current version of the docs to the folder with its version and create a new version of the docs under current.

Read the Docs does support versioned documentation by default, but it seems like Github Pages is a bit more limited in that regard since its not meant to be as sophisticated.

There is some more work that would need to be done for a new version aside from just copying the docs:

• If we have version strings in multiple places in the docs, we will need to remember to update those every time. One can mitigate this problem by defining the version string using page variables in each page's front matter. Then the variable only needs to be defined per page. We shouldn't need to explicitly refer to versions in many pages, but for example the installation instructions come to mind.
• The navigation sidebar is based on links relative to the project root, meaning that the version number is contained in each path in the navigation.yaml. This means that for a new version, we would have to basically copy the navigation configuration and adjust the paths, i.e. create a new sidebar navigation for each version. This is not too difficult, but you would need to at least be a bit familiar with the Minimal Mistakes configuration since you also need to define to which scope the navigation is applied.
• Some pages contain relative links to other parts of the documentation, i.e. the library overview page links to many different pages. The links are relative to the project root and would therefore also contain the version number. I do not know whether it is possible to make the links relative to the parent folder of the markdown file instead.

In terms of how to select the version, I think we could just add a selector to the masthead (like Gradle does it).
This would then just direct you to the version folder and then you would see that folder's index.html (I tested this).

We will also need to redirect from the root index.html to the current/index.html. Here is a question on how to do this (I have not tested it yet).

Anyways, I think this is something to worry about once we actually need docs for multiple versions.

[JanBobolz]

I'm not totally against this, but: it's not like we support old versions, anyway (in contrast to, perhaps, gradle et al.).

So my simple suggestion for how to handle this would be:

• Version the documentation page similarly to the main libraries, i.e. have a main branch that's published onto the website and push updates for future versions onto develop, to be merged and tagged when new library versions are relasesd. The github.io page always references the most recently released lib version.
• For anyone who really wants the old documentation versions, they are accessible via git with the appropriate tag (maybe even a github release that contains the site as zipped html or something).

What do you think? My goal here is to avoid some maintenance overhead and keep things simple :)

[rheitjoh]

I like that idea. Should be easy to offer old docs by tagging the gh-pages branch since that contains the fully rendered site.