Add tag-based release versions to RTD

[joshuacwnewton]

I notice our documentation only has a single version: v: latest. That means that changes to the documentation appear immediately once merged (independent of our release cycle).

I think it would be good to activate versions based on our release tags, so that we have a stable snapshot of what the docs looked like exactly on release. That way, future changes to the docs don't end up being misleading for people who are sticking with an older release. (Without this, development of the docs will become out of sync with the development of SCT.)

More info here: https://docs.readthedocs.io/en/stable/versions.html#states

[joshuacwnewton]

I have changed the following settings in RTD:

• Changed our default version (i.e. what spinalcordtoolbox.com redirects to) to stable instead of latest. (stable means the most recent versioned release.)
  • I did this because I assume most of our users are coming from a stable release, rather than installing from the git repo, which is more advanced.
• Enabled 5.0.0 release. (This isn't super relevant right now, because 5.0.0 == stable, but as soon as we put out a new release this will become relevant.)
• Enabled Show version warning, which alerts users if they are viewing documentation from an older release. (Again, will be more relevant in the future after new releases.)
• Changed some project-based RTD metadata (programming language, tags)

I also tried enabling 4.3, but as expected, the build for that version failed. It failed because of a lack of readthedocs.yml in 9ea4c9b. Perhaps a patch could be issued for 4.3 just to get the documentation loading, as I'm sure many users will still use 4.3. But, I'm not sure the functional differences between 4.3 and 5.0.0 are so great that it's urgent to do this.

@jcohenadad if all of this sounds good then feel free to close this issue.

[jcohenadad]

Awesome contribution @joshuacwnewton !!! 💯

Perhaps a patch could be issued for 4.3 just to get the documentation loading, as I'm sure many users will still use 4.3. But, I'm not sure the functional differences between 4.3 and 5.0.0 are so great that it's urgent to do this.

Agreed, not worth spending time doing this

@jcohenadad if all of this sounds good then feel free to close this issue.

we could add the cherry on the cake: displaying the version right below the logo, e.g. as done for ivadomed:

I originally removed it from the custom css by putting the white color, but we could easily add it back:
https://github.com/neuropoly/spinalcordtoolbox/blob/c29d6c332662ae8fad0954f70991f35078d5c399/documentation/source/_static/css/custom.css#L2

We might also need to reactivate a tag in the conf.py file.

[joshuacwnewton]

I originally removed it from the custom css by putting the white color, but we could easily add it back:

#000000 is black, so all I needed to do was reactivate a setting in conf.py as you said. :)

EDIT: Oh, very interesting. GitHub's markdown automatically renders color hex codes.... #FFFFFF #FF0000