Navigation bar in 404 pages for older versions points to /stable

[astrojuanlu]

Details

• Read the Docs project URL: https://readthedocs.org/projects/kedro/

Expected Result

We are using https://sphinx-notfound-page.readthedocs.io/ to generate good-looking 404 pages on Read the Docs instead of the classic "maze found" page. This is a net improvement over what we had earlier. kedro-org/kedro#2486

We'd like these 404 pages to retain the navigation menu of older versions.

Actual Result

A description of what actually happened

1. Open a URL that exists in /stable or /latest, for example https://docs.kedro.org/en/0.18.12/configuration/configuration_basics.html
2. Switch the version in the flyout menu to an older one and arrive to a 404 page produced by sphinx-notfound-page, for example to 0.18.5
3. Realize that the navigation links all point to /stable and wonder how is one supposed to reach the older version of the docs now ❓
4. Try clicking the 0.18.5 version again in the flyout, only to land in https://docs.kedro.org/en/0.18.5/404.html with the navigation still pointing to /stable
5. In frustration, click on the logo to go to the index, and switch version again, this time for real

Looking at https://sphinx-notfound-page.readthedocs.io/en/latest/configuration.html#confval-notfound_urls_prefix, we now realize that maybe this is intended behavior and sphinx-notfound-page is not a good solution for us. Do you know what could be an alternative that still gives a 404 page under our control, but retains the navigation? Should we add a 404.html to all older versions and rebuild them?

cc @stichbury

[astrojuanlu]

I think this is essentially the same issue as ansible/ansible-documentation#94

[humitos]

Should we add a 404.html to all older versions and rebuild them?

Yes. (this is the short answer 😄 )

---

Right now, Read the Docs finds a 404.html in the current version you are reading, if it's not there, it tries the default version (in your case, stable). Since there is no 404.html page on the 0.18.5 version, it uses the one that found from stable. That's why all the links in the navigation bar points to stable version.

Unfortunately, there isn't too much Read the Docs can do here, but the solution would be to add the sphinx-notfound-page extension and re-build all the older versions.

[humitos]

Unfortunately, there isn't too much Read the Docs can do here

I'm sure there are some other hacky JS solution that could be implemented. However, they would be pretty fragile and won't work for all the use-cases --but it's probably something you can implement on your side if you have a limited use-case.

I'm just thinking about "rewrite all the links with link.replace("/en/stable/", "/en/<current version>/") via a javascript in the 404.html page from the stable version" 🧑‍💻

[astrojuanlu]

Thanks a lot @humitos! Knowing that I'm on the right path is reassuring anyway.

I guess this would be easier if we followed branch-based versioning, as you suggest in this blog post of yours I keep coming back to...

In any case, happy to close this issue.