Use sphinx-multiversion to support documentation for multiple versions

[tomicapretto]

I added sphinx-multiversion to support the creation of docs for each release. I have also created a jinja template to put the links for the different versions and also some information. The gh-pages-redirect.html refers to a wrong link, I'm going to fix it later.

Illustrative gif

[tomicapretto]

Tagging @OriolAbril, who might be interested

[codecov-commenter]

Codecov Report

Merging #349 (b40a6d2) into master (754ea32) will not change coverage.
The diff coverage is n/a.

❗ Current head b40a6d2 differs from pull request most recent head 7832f66. Consider uploading reports for the commit 7832f66 to get more accurate results

@@           Coverage Diff           @@
##           master     #349   +/-   ##
=======================================
  Coverage   90.28%   90.28%           
=======================================
  Files          13       13           
  Lines        1348     1348           
=======================================
  Hits         1217     1217           
  Misses        131      131           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 754ea32...7832f66. Read the comment docs.

[OriolAbril]

Does this rebuild all the documentation for all versions every time docs are built? I am not sure I understand how it works so that old versions show the links to newer versions, versions var looks static once defined/computed from tags in conf.py right?

[tomicapretto]

Does this rebuild all the documentation for all versions every time docs are built? I am not sure I understand how it works so that old versions show the links to newer versions, versions var looks static once defined/computed from tags in conf.py right?

Yes, unfortunately, it rebuilds all docs for all versions every time you build it. I still don't know if it is possible to only build what has been modified. And yes, I think versions is static. here there is information about the objects exposed.

EDIT: I haven't read in detail but this problem is discussed here.

[OriolAbril]

Yes, unfortunately, it rebuilds all docs for all versions every time you build it. I still don't know if it is possible to only build what has been modified.

It is provided you have some cool javascript that generates the version menu dinamically from a json file (shared between all versions). IIUC, this is what readthedocs and documenter do. Documenter works seamlessly doing this with GitHub pages (see ArviZ.jl docs pages, respective html and source), but so far I have not seen anything close in python and I don't understand why but I also don't know enough of CI, javascript, html or any of the skills needed to actually do this

[tomicapretto]

There are two projects that use sphinx-multiversion without re-building everything from 0, here and here. But they use a version of the package that is not merged yet (this PR). I'm not sure if we should follow them and do the same here, having to keep an eye close to the development of sphinx-multiversion, or just keep using sphinx and add a GitHub action to automatically build the latest release documentation and upload to gh-pages.

[tomicapretto]

I'm merging to test if this works well... Hope not to break anything 🙏