Support multiple versions in the website documentation

[bogdanromanx]

The documentation is currently updated prior to a minor release with the supported functionality, thus losing the information of what is supported on each version. The immediate impact is that documentation cannot be written unless the functionality is completed because it needs to be deployed only after the release.

The support of multiple versions within the documentation would allow a smoother evolution of the documentation during development where a "in development" meta version can be updated for each individual functionality added to the system.

General requirements:

• the documentation must remain at https://bluebrainnexus.io/docs without affecting the product website
• it must support markdown with html customisations
• it must be searchable
• it must allow checking references
• it must support multiple versions (with navigation between version)
• it must be controlled through CI (deployment from the master branch)
• optionally: it must notify users that are browsing an older version of the documentation to navigate to the latest released version

[imsdu]

To keep older versions of the documentation, there is a PR in sbt-ghpages that has been opened for ages:
sbt/sbt-ghpages#39

But from what I saw, the best approach is the one adopted by typelevel for cats-effect.

There is a special branch for docs: https://github.com/typelevel/cats-effect/tree/docs

• This branch contains git submodules pointing to the branches of the versions 2.x and 3.x
• Dependabot updates the references of the submodules
• A github action is launched to build the docs and deploy to github pages: https://github.com/typelevel/cats-effect/blob/docs/.github/workflows/microsite.yml

For the message about the old version, akka just includes a simple js asset in paradox that parses the url: https://github.com/akka/akka/blob/master/akka-docs/src/main/paradox/assets/js/warnOldDocs.js

[imsdu]

An alternative that still uses sbt-ghpages is described here:
sbt/sbt-ghpages#10 (comment)
That seems the approach taken by sbt:
https://github.com/sbt/website/blob/0.13/project/Docs.scala#L162

[imsdu]

Paradox seems to have a feature to show a warning when the user is not looking at the current version:
https://developer.lightbend.com/docs/paradox/current/configuration.html#version-warning
Which seems to have a minor bug: lightbend/paradox#417

[imsdu]

An example of what I can achieve while relying on Paradox:

imsdu@f6ac2fc

Main aspects:

• The solution relies on git submodules, the branch is created with no history
• Current docs and contexts are published on /
• Snapshot docs and contexts are meant to be published on /snapshot
• v1.4.x docs are meant to be published under /v1.4.x
• The version page is the same for all version and has a copy for each of them (its content is just an example).
• The version is overriden to display the version related to the branch and not a commit/tag

We are quite limited by Paradox and the theme we used:

• The first one does not have a lot of updates and the second one is dead
• Paradox is not made with versioning in mind (Lightbend does not need it)
• In the navigation menu (on the left), we can't have pages that are not included in the project (so no way to have a external version page or to point directly from this menu to the different docs)
• For some reason, customizing templates work while calling the paradox command but not the makeSite command
• When using a variable (ex: the doc version) inside a #h1, the h1 value is correctly displayed in the page content but not in the header

[imsdu]

What an older version can look like:

[imsdu]

Completed when merging #2555