search

readthedocs / readthedocs.org

The source code that powers readthedocs.org
https://readthedocs.org/
MIT License
8.06k stars 3.59k forks source link

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

Closed remram44 closed 6 years ago

remram44 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

See also #1616.

stsewd commented 6 years ago

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 commented 6 years ago

Couldn't it just point to the default branch?

ThomasWaldmann commented 6 years ago

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 commented 6 years ago

@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 commented 6 years ago

Maybe related to #3595

stsewd commented 6 years ago

As commented https://github.com/rtfd/readthedocs.org/issues/1856#issuecomment-177037500 and https://github.com/rtfd/readthedocs.org/issues/1856#issuecomment-362643595. 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 https://github.com/rtfd/readthedocs.org/issues/1616