Improve "404 not found" pages on the documentation

[astrojuanlu]

Description

#2486 fixed #2464, and the current situation is much better than what we had.

However, navigating to old versions of the docs is hard: readthedocs/readthedocs.org#10643

It would be better if 404 pages reflected the navigation structure of each version.

Context

Used very often by @stichbury and the rest of the team to see how a specific page used to look.

Possible Implementation

I think there's an undocumented feature of Sphinx in that one can add a 404.md page to the docs (if it's documented, I haven't found it). That should be a solution going forward.

For older versions, it's more complicated. We could create a branch in the repository for each version we want to amend (not necessarily all of them) that adds such a page.

Apart from all this, we should probably keep the sphinx-notfound-page extension for the time being.

Possible Alternatives

[astrojuanlu]

Examples:

• https://github.com/wpilibsuite/frc-docs/blob/main/source/404.rst
• https://github.com/ansys/ansys-sphinx-theme/blob/main/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/404.rst

(By the way, this explanation is top notch ⭐ https://sphinxdocs.ansys.com/version/stable/user_guide/404_page.html)

[stichbury]

@astrojuanlu Given the discussion in #2980 should we now focus our attention on branches for adding 404 pages just for v 0.17.7 and for 0.18.0 onwards (with possible omission of 0.18.0-0.18.4 as they're not indexed)?

[astrojuanlu]

Indeed, we can do a proof of concept with 0.17.7, and if it works extend it to 0.18.5 onwards.

For now, let's add a 404 page in the main branch, so it works with latest and soon stable too.

[astrojuanlu]

Is it possible to do a "did you mean?" page on 404 which offers URLs suggestions? This is my biggest gripe doing user support as I search for page which no longer exists on a newer version.

_Originally posted by @datajoely in #4257

[astrojuanlu]

Missing:

• 1. Examples of this happening in the wild
• 2. A better definition of the outcome

[astrojuanlu]

cc @stichbury could you help me with (1)? and I'll describe (2) in a bit more detail

[stichbury]

Some ideas for examples in the wild:

1. This is quite nice because it brings up an explanation and a search box, prepopulated with the URL you tried to find, and the results of that search for you to choose from:

(results from https://ably.com/docs/general/push/publis?q=dafd)

---

2. Basic search bar (not populated) to help move people onwards

---

3. From ARM developer docs

---

4. This is very basic but gives a contact (we could push people at Slack)

[astrojuanlu]

We'll possibly need to add custom tracking for those errors https://community.heap.io/using-the-product-46/possible-to-track-web-errors-like-400-401-403-554?postid=1542#post1542

[astrojuanlu]

I initially described the problematic navigation in readthedocs/readthedocs.org#10643 (comment), but with the new add-ons, the logic has changed: readthedocs/addons#223

As a result, now it's impossible to land in a 404 page when switching versions. The downside though is that navigating across versions is more difficult now.

[stichbury]

Looking at this again and I'm not convinced there's anything more we can do. Would adding a 404.md page have any advantages over the current situation of using the extension, given the add-ons have changed the logic of this situation? I'm happy to try it if so, otherwise let's close this.

[astrojuanlu]

Indeed, I think there's not much for us to do here until we have more clarity on readthedocs/addons#211. Closing for now.