Improve version comparison

[domenkozar]

Pyramid uses version "XX-branch" to track changes to minor versions in git branches. However currently readthedocs just assumes any version is latests if versioning scheme is too complex to compare.

This means no warning is shown to users that they are reading outdated documentation.

I suggest javascript/console error is thrown at the same time to note developers to fix this. Next step would be to have setting in project to denote what documentation versions are latest to override autodetection.

[ericholscher]

Hrm, not really sure throwing a JS error is that great of an idea. I guess it doesn't hurt anything in the end. I don't know a good solution to this problem, but making it more visible might be useful. In the end, people just need to conform to correct versioning schemes, but that's hard to change after the fact :/

[domenkozar]

The main issue we currently have is that we assume branch names correspond to resolvable version numbers. An alternative would be to provide text input besides branch names that would explicitly specify what version of documentation it is. If we can parse version from conf.pybefore building it, even better.

[domenkozar]

A sane way would be to add latest dropdown to project settings page. Or to give each version an alternative string that rtd can compare.

[ericholscher]

Another good idea: highlight the current version in the lists of versions.

[glarrain]

@iElectric I'm not sure parsing conf.py is a good choice, since some projects choose to have a dynamic and DRY approach at versioning, defining the version only say, /init.py, and then extracting it appropriately for setup.py version scheme, Sphinx conf.py's, etc. Do I make sense?

[ericholscher]

We should sort versions based on usage. Should be pretty easy to add that in soon.

[domenkozar]

Awesome!

[glarrain]

what about new versions being released? Obviously the old ones would've been used more. Perhaps the sorting should be based on when was that version added? In that case, something would need to be done in the transition from the current behavior to the new one

[ericholscher]

We have release this code now and updated it. Closing this because it refers to old code.