Version chooser: Stay on the same page when switching versions

[amotl]

About

@hlcianfagna suggested to improve the version chooser in a manner that it will try to select the same page the reader is currently viewing, when switching versions.

[amotl]

Dear Hernan,

the situation has been improved with GH-420, which has been released already. Are you satisfied with the outcome? Obviously, it will not work in all situations, when content has been restructured. But when the shape is the same, like on ¹, it seems to work well.

With kind regards,
Andreas.

Footnotes

1. https://crate.io/docs/crate/reference/en/5.4/concepts/storage-consistency.html ↩

[hlcianfagna]

Hi, it works well now, but at the UI level there is one thing that is confusing, the version number in the dropdown is itself a link to the base page of the documentation for that version.

[amotl]

Hi again. GH-428 tries to improve the situation. It has not been rendered on all the documentation projects, but, for example, https://crate.io/docs/python/ already uses the corresponding theme release which includes this fix.

Please let me know if you can discover any further flaws with this navigation component, or related details. Thanks!

[hlcianfagna]

Thank you.
There may still be some room for improvement, for instance if you go to
https://crate.io/docs/python/en/latest/connect.html
and open the version dropdown you get offered 0.30, 0.23, and 0.22
Selecting 0.23 it stays on the Connect page but the navigation tree on the left-hand side is collapsed.
Selecting 0.22 it navigates to the page not found message.

[amotl]

Dear Hernan,

thanks.

Selecting 0.23 it stays on the Connect page but the navigation tree on the left-hand side is collapsed.

That's true. You will also recognize that, after navigating to https://crate.io/docs/python/en/0.23/, the version chooser swaps back to its previous version, where the current version is still a link. That means that this page has not been rendered using the latest version of the theme, yet.

Selecting 0.22 it navigates to the page not found message.

That's true. On version 0.22, there was no connect.rst page, see https://github.com/crate/crate-python/tree/0.22.1/docs. In this cases, the very light-weight component can't do anything.

Visiting its source code recently, PyData Theme's version switcher might be more capable on this matter, but that is definitively out of scope for those little improvements we can make right now.

With kind regards,
Andreas.

[amotl]

I've just deactivated those old versions of the documentation for the Python driver. I see no reason to keep them around. So, effectively, they are all gone now.

• https://crate.io/docs/python/en/0.22/
• https://crate.io/docs/python/en/0.23/
• https://crate.io/docs/python/en/0.30/

We may even think about changing the versioning scheme of those artefacts in the future, because they are mostly stable pieces of software, where different versioning schemes may fit better. However, that is also a totally different story.

[amotl]

Problem Report

@michaelkremmel reported about quite a number of "404 Not Found" responses, which are most probably caused by the new version chooser component.

Examples:
[...]
https://crate.io/docs/crate/reference/en/3.3/appendices/release-notes/5.4.0.html
https://crate.io/docs/crate/reference/en/3.3/appendices/release-notes/5.4.1.html
https://crate.io/docs/crate/reference/en/3.3/appendices/release-notes/5.4.2.html
https://crate.io/docs/crate/reference/en/3.3/appendices/release-notes/5.4.3.html
https://crate.io/docs/crate/reference/en/3.3/appendices/release-notes/5.5.0.html

Seitenblicke

This is probably one of the reasons why pydata-sphinx-theme populates its version switcher dropdown using JavaScript on page load.

• components/version-switcher.html#L10-L12
• scripts/pydata-sphinx-theme.js#L327-L348

Solution

Use the code from pydata-sphinx-theme, adjusted a bit, in order to achieve the same thing.

• Add version chooser JavaScript helpers derived from pydata-sphinx-theme #436

[amotl]

Hi again,

with GH-436, we added the JavaScript version chooser component of pydata-sphinx-theme, in order not to produce any static links pointing to non-existent resources, in turn yielding "404 Not Found" responses. Its author, @drammock, also provided valuable insights and suggestions to use a more recent version -- thank you again!

@hlcianfagna: Please let us know if that satisfies your claims for reasonably good UX, or if you see any room for improvements.

With kind regards,
Andreas.

[hlcianfagna]

@hlcianfagna: Please let us know if that satisfies your claims for reasonably good UX, or if you see any room for improvements.

Hi, yes, I am happy that the main objective of staying on the same page is now achieved. Ideally I would have liked that we filter out the versions for which the page does not exist or that maybe we give a more graceful message while staying on the same page, but I understand these are larger changes and also things that may be better addressed upstream on the standard components. So no objections from me to close this issue.