Branches and the "not using the most up to date version" note

[remram44]

In order to be able to add corrections to my docs, and FAQ entries and the like, I use release branches as the versions on RTD. For instance, I have a 0.6.x branch, then 0.7.x, 0.8.x.

This has worked fine for me in every way, except that it breaks the "You are not using the most up to date version of the library" feature.

1. When the feature is triggered, the message says "0.5.1 is the newest version"; however 1.0.3 is the newest version. 0.5.1 just happens to be the latest tag for which I build the docs (then I switched to using branches).
2. The feature is only triggered on doc pages built for a version that corresponds to a tag. If I visit the docs for 0.6.x, there will be no message at all.

My recommendations are the following:

1. Allow the target of the note to be configured, or just use the "default version" (the one / redirects to) instead of the most recent tag
2. Trigger it everywhere (perhaps change the wording a little bit, since you might be viewing the docs for a development branch that is ahead of the latest release, but I think there is value in indicating both when it is not the latest release and when it is not a release at all).

Example message: http://reprozip.readthedocs.org/en/0.4/packing.html

[ericholscher]

Agreed, we should probably remove this feature. It would be great if you could submit a PR working on this, the code is here: https://github.com/rtfd/readthedocs.org/blob/304de09d9253c464ea6ee5b8999d2d8886c83fdd/readthedocs/core/static-src/core/js/doc-embed/version-compare.js#L18

[ThomasWaldmann]

See also #1616.

[stsewd]

This is because 0.6.x, 0.7.x, 1.0.x and so on aren't valid versions according to PEP440. RTD uses this library for get the version order, if one version is not valid, it is omitted.

[remram44]

Couldn't it just point to the default branch?

[ThomasWaldmann]

Why does it try to parse a BRANCH name as version anyway?

A release has a version and is a TAG, not a branch.

[stsewd]

@ThomasWaldmann currently RTD support both kind of work-flows (tags and branches), but if the project has at least one tag, those are given priority (see #3528)

[stsewd]

Maybe related to #3595

[stsewd]

As commented #1856 (comment) and #1856 (comment). The issue wasn't a bug but related to an invalid version name (PEP440), which is documented on the docs https://docs.readthedocs.io/en/latest/versions.html#how-we-envision-versions-working.

Also, the team has decided to implement #1616