Sidebar doesn't have links updated to versions other than latest when selecting another version

ansible / ansible-documentation

Ansible community documentation

https://docs.ansible.com/

GNU General Public License v3.0

83 stars 488 forks source link

Sidebar doesn't have links updated to versions other than latest when selecting another version #94

Open Porkepix opened 3 years ago

Porkepix commented 3 years ago

Summary

Older Ansible versions doc is a pain to go through with the sidebar not updated at all to match older versions documentation, the result is that many links in the sidebar go back to latest version, and if the user try to again select an older version, then it'll pretty often end up on a non-existing page because doc's structure changed in-between. For example it can lead to https://docs.ansible.com/ansible/2.9/collections/all_plugins.html

Issue Type

Documentation Report

Component Name

sidebar

Ansible Version

Older versions

Configuration

Unrelated for doc

OS / Environment

Unrelated for doc

Additional Information

This would make the doc much more usable for older versions of Ansible than the latest one.

Code of Conduct

[X] I agree to follow the Ansible Code of Conduct

ansibot commented 3 years ago

Files identified in the description: None

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

samccann commented 2 years ago

Hi @Porkepix What I think you are hitting here is a limitation with our customized 404 page. If you go from a 2.9 page to a /latest/ page using the version selection on the sidebar, it should work, with the exception, as you say, of pages that have moved. When the docsite can't find the page, it used to put up a vanilla 404 page with no sidebar at all. Now it puts up the sidebar for latest only as that is what the code supports. We do have another issue tracking where we need to put redirects in place for common 2.9 pages that no longer exist - https://github.com/ansible/ansible/issues/71927

I'll leave this issue open for a bit in case I'm misinterpreting what you are reporting. Otherwise, please add specific problem pages to that other issue so we can add manual redirects as needed.

ansibot commented 2 years ago

@Porkepix This issue is waiting for your response. Please respond or the issue will be closed.

click here for bot help

Porkepix commented 2 years ago

Problem's still here. To get through more explicitly @samccann, here are some STR:

Visit https://docs.ansible.com/ansible/latest/collections/index.html
Switch to 2.9 in the sidebar
You'll get a page saying it can't find the resource (up to here it's normal, such docs didn't exist back at Ansible 2.9)
Now you can see that the whole sidebar is still the latest one instead of having changed to 2.9
Selecting 2.9 in the sidebar will make you return to point 3
You'll quickly understand you can't get the 2.9 sidebar at all that way to search through it what you're looking for, apart from getting to a page that have an equivalent/is linked between 2.9 and latest.

In the end, when user switch version in the sidebar, whether it is 2.9, latest or devel, the sidebar should be updated and changed accordingly, no matter if the page is found or not.

samccann commented 2 years ago

Thanks @Porkepix for the detailed description. While I agree with your description of how it works, I don't know that we have a solution for it. Unfortunately, this is a side effect of the extension we use to give us the 404 page -https://pypi.org/project/sphinx-notfound-page/

looking at this issue in that project, maybe there are alternatives here we can experiment with. It would require changing code in older releases on first review, but I agree this is an annoying side effect of having a usable 404 page. (The older approach was just a blank 404 page with no navigation at all). Thanks for the description and I'll experiment a bit and see if that issue gives me the hints I need to improve this behavior.