Flyout: sort by version number, not lexicographically #222
Comments
|
I made the decision of sorting the version alphabetically by default on purpose. This is mainly to have a pretty simple and well defined sorting algorithm that everybody can easily understand. In the old flyout, we use a pretty custom sorting algorithm that almost nobody understands, has lot of edge cases, and it's not possible to change without breaking people's documentation. I'm trying to avoid this pattern in the new flyout implementation. This is the code of the "custom sorting algorithm" ™️ :
My idea is to make the sorting algorithm configurable via readthedocs/ext-theme#211 by exposing different sorting options to users, making each of them as clear as possible to manage different use cases (e.g. alphabetically, CalVer, SemVer, etc). I don't know when this is going to be available, but I remember having issues on the logic for SemVer when working on the notifications addon at #71 and that's why I ended up implementing a pretty basic "is That said, I'd appreciate any feedback anyone can provide here. I will take it into consideration when jumping into this work 👍🏼 |
humitos
changed the title
|
Interesting. While doing some research about how to implement this, I found that depending on the PEP440 pattern you choose, it may be possible to sort it lexicographically or not: https://github.com/mbarkhau/bumpver#pattern-examples |
Allow users to choose one of the pre-defined algorithms: - Lexicographically - SemVer (Read the Docs) - CalVer - Custom pattern The sorting algorithm is implemented in the backend. So, the list returned under `addons.flyout.versions` will be sorted acordingly the algorithm the user chose. There is no need to do anything extra in the front-end. The algorithm follows the next general rule: _"all the versions that don't match the pattern defined, are considered invalid and sorted lexicographically between them and added to the end of the list"_. That means that valid versions will appear always first in the list and sorted together with other _valid versions_. There is one _key feature_ here and is that the user can define any pattern supported by `bumpver`, which is the module we use behind the scenes to perform the sorting. See https://github.com/mbarkhau/bumpver#pattern-examples On the other hand, `SemVer (Read the Docs)` is implemented used the exact same code we were using for the old flyout implementation. This is mainly to keep backward compatibility, but its usage is not recommended since it's pretty hard to explain to users and hide non-clear/weird behavior. Closes readthedocs/addons#222
|
I opened a PR for this and I'd appreciate any feedback you may have about it: readthedocs/readthedocs.org#11069. It implements different sorting algorithms and let the user to choose between them or create their own if required. |
|
I didn't forget about this 🙏🏽 |
|
@astrojuanlu Thanks for the ping. Everything is on its place. The PR is waiting for a final review. Hopefully, it will be deployed next Tuesday. |
* Addons: sorting algorithm for versions customizable on flyout Allow users to choose one of the pre-defined algorithms: - Lexicographically - SemVer (Read the Docs) - CalVer - Custom pattern The sorting algorithm is implemented in the backend. So, the list returned under `addons.flyout.versions` will be sorted acordingly the algorithm the user chose. There is no need to do anything extra in the front-end. The algorithm follows the next general rule: _"all the versions that don't match the pattern defined, are considered invalid and sorted lexicographically between them and added to the end of the list"_. That means that valid versions will appear always first in the list and sorted together with other _valid versions_. There is one _key feature_ here and is that the user can define any pattern supported by `bumpver`, which is the module we use behind the scenes to perform the sorting. See https://github.com/mbarkhau/bumpver#pattern-examples On the other hand, `SemVer (Read the Docs)` is implemented used the exact same code we were using for the old flyout implementation. This is mainly to keep backward compatibility, but its usage is not recommended since it's pretty hard to explain to users and hide non-clear/weird behavior. Closes readthedocs/addons#222 * Use alphabetically instead of lexicographically * Link BumpVer pattern examples * Migration help_text * Add bumpver as requirements * Addons: allow to put `stable` and `latest` first when sorting * Mark the string as translatable * Install `bumpver` in the requirements * Migrations update * Rename field to match sorting (latest, stable) * Fix migrations * Fix algorithms * Add tests for sorting algorithms * Minor fixes * Add tests for `AddonsConfigForm` * Test: reduce the number of queries in 1 * Use descending sorting for _valid versions_ It makes more sense to show `latest stable <newest>` than `<oldest>` first. #11069 (comment)
|
A feature to sort versions in the beta addons flyout was released today. To enable this feature, you will need to activate the new beta addons in your project first, and then edit the sorting from the project's setting using the new beta dashboard from https://beta.readthedocs.org/. Please, let me know any feedback you may have 🙏🏼
|
Thank you ❤️ |
Right now versions are sorted in alphabetical/lexicographical order, which produces some funny results
The text was updated successfully, but these errors were encountered: