Make documentation site work with multiple versions

[andreslucena]

🎩 What? Why?

As I mentioned in #9916, we have a problem that currently instructions in https://docs.decidim.org are always on develop. This is problematic, some examples from http://chat.decidim.org from the last couple of months:

• Users were trying to use Environment Variables that weren't there for v0.26
• Users were trying to install v0.27 with Ruby v.2.7.5 (it should be v3.0.2)

📌 Related Issues

• Related to Bump versions on install docs #9916

Testing

As there are two repositories each with 3 branches it's tricky to try this out locally. What I've done is:

git fetch origin
git checkout release/0.26-stable 
# Change docs/antora.yml version to v0.26
git add docs/antora.yml  && git commit -m "Bump version for Antora"
git checkout release/0.27-stable 
# Change docs/antora.yml version to v0.27
git add docs/antora.yml  && git commit -m "Bump version for Antora"
git checkout develop 
# Change docs/antora.yml version to develop
git add docs/antora.yml  && git commit -m "Bump version for Antora"

# In another directory
git clone https://github.com/decidim/documentation.git
cd documentation 
npm install 
git fetch origin 
git checkout develop 
# Change the url in the decidim/decidim source to your local path, ie /home/apereira/Work/decidim/decidim 
npm run build
xdg-open build/site/index.html 

Mind that if you don't do all these steps, you'll have this error message:

$ npm run build

> decidim-documentation@ build /home/apereira/Work/decidim/documentation
> antora antora-playbook.yml $@

[17:07:21.941] FATAL (antora): Duplicate page: master@en:configure:environment_variables.adoc
  1: docs/modules/configure/pages/environment_variables.adoc in https://github.com/decidim/decidim (ref: develop)
  2: docs/modules/configure/pages/environment_variables.adoc in https://github.com/decidim/decidim (ref: release/0.26-stable)
Add the --stacktrace option to see the cause of the error.
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! decidim-documentation@ build: `antora antora-playbook.yml $@`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the decidim-documentation@ build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/apereira/.npm/_logs/2022-10-20T15_07_21_995Z-debug.log

This is because you don't have the correct version names or URLs configured in your repositories.

📷 Screenshots

(The idea is that after #9916 is merged, when you go to develop you'll have ruby 3.1.1, but on v0.27 you'll have 3.0.2)

doc-muilti-version-branches.mp4

♥️ Thank you!

[andreslucena]

Mind that for this to work on https://docs.decidim.org, we'll also need to change the Antora default branch. We can do that after these three PRs are merged (#9917, #9918 and #9919)

[ahukkanen]

Really nice improvement! Something that will be extremely useful for everyone.

Just one suggestion below as I think the more we can automate things, the less mistakes we will make along the line.

[ahukkanen]

One more small cleanup.