Revisiting multi-version naming

[jorgepiloto]

🐞 The problem
The multi-version logic of our actions only consider <MAJOR>.<MINOR> versions. This versions is assumed to be always the latest patch release for that major and minor. Thus, the multi-version shows values like the following ones:

dev                  # 0.66.dev0
0.65 (stable)        # 0.65.3
0.64                 # 0.64.5
0.63                 # 0.63.12
0.32                 # 0.32.1

As per #217, we would like to handle pre-releases. These releases include suffixes like alpha, beta and rc. This feature introduces some corner pointed out by @greschd, for example:

0.2rc0               # 0.2.0-rc0
0.2                  # 0.2.0
0.2rc0 ??            # 0.2.1-rc0 !!

As per our internal discussion, it may be more convenient to follow pure semantic versioning when listing out the versions in the drop-down selector for the multi-version. This is more explicit:

0.2.0-rc0            # 0.2.0-rc0
0.2.0                # 0.2.0
0.2.1-rc0            # 0.2.1-rc0

Right now, the version for the multi-version is extracted from the major and minor numbers of the tag vX.Y.Z. If we want to support suffixes, we also need to come up with an agreement on how to include those in the tags.

[RobPasMue]

I understand the above issues and there might not be an easy solution...

However, in the meantime, I propose the following approach:

Switcher behavior

As it is right now. This means, that we just keep showing MAJOR.MINOR versions, and we default to the latest patch version. This is what most Python libraries do in fact... see https://numpy.org/doc/stable/index.html

Access to all released versions

After ansys/[email protected], our documentation will automatically have a site with all the documentation versions available (not only the ones on the switcher, potentially, but all the ones stored on the site). That could give us access to all the released versions. See https://actions.docs.ansys.com/version/

More explanations

What I am saying is basically that now the following folder structure could be accepted:

version
|-- dev
|-- stable
|-- 0.3.3
|-- 0.3.2
|-- 0.3.1
|-- 0.3.0
|-- 0.3.0-rc0
|-- 0.3
|-- 0.2.2
|-- 0.2.1
|-- 0.2.1-rc0
|-- 0.2.0
|-- 0.2
...

The switcher, however, would only show the following entries

dev
0.3 (stable)
0.2
...

Changes to be implemented

• Our actions uploading the documentation would now also have to upload the current docs to a patch folder, in such a way that the
  "same" docs are now uploaded at

  stable
  0.3
  0.3.X
  

  whenever we do a release for 0.3.X. However, the first two sill have a "rolling" behavior. The moment a new patch version is released, they will be overwritten.
• Also the index generated at CNAME/version/index.html would have to detect all folders (if it is not doing it automatically)

Benefits

• Not an "intrusive" operation - behavior is kept the same on the actual multi-version documentation approach
• All our released versions docs will be kept track of at our gh-pages branch - we therefore retain the docs for a specific patch version! We are losing access to them right now, the moment the next patch released version comes out.
• We gain access to release candidate versions as well, since the folder can be uploaded anyway, even though it does not show up in the switcher. Users will be able to access it through the CNAME/version/index.html site. See https://actions.docs.ansys.com/version/

Downside

• The access to the documentation for release candidates, alpha releases etc. is still a bit offuscated. But at least they will be published now and users will have access to it through the CNAME/version/index.html site.