Docs: sphinx-notfound-page doesn't show nicer 404 page

[nineteendo]

Documentation

The sphinx not found extension introduced in #111084 doesn't seem to be installed when the documentation is published: https://docs.python.org/3/-

This is how it's meant to look: https://cpython-previews.readthedocs.io/en/3.14/-

cc @hugovk

Linked PRs

• gh-125895: Docs: fix 404 page prefix configuration #139386

[hugovk]

I can see the extension is installed in the venv on the docs server, for example:

./venv-3.14/lib/python3.10/site-packages/sphinx_notfound_page-1.0.4.dist-info
./venv-3.14/lib/python3.10/site-packages/sphinx_notfound_page-1.0.4.dist-info/RECORD
./venv-3.14/lib/python3.10/site-packages/sphinx_notfound_page-1.0.4.dist-info/WHEEL
./venv-3.14/lib/python3.10/site-packages/sphinx_notfound_page-1.0.4.dist-info/INSTALLER
./venv-3.14/lib/python3.10/site-packages/sphinx_notfound_page-1.0.4.dist-info/LICENSE
./venv-3.14/lib/python3.10/site-packages/sphinx_notfound_page-1.0.4.dist-info/REQUESTED
./venv-3.14/lib/python3.10/site-packages/sphinx_notfound_page-1.0.4.dist-info/METADATA
./venv-3.14/lib/python3.10/site-packages/notfound
./venv-3.14/lib/python3.10/site-packages/notfound/__pycache__
./venv-3.14/lib/python3.10/site-packages/notfound/__pycache__/__init__.cpython-310.pyc
./venv-3.14/lib/python3.10/site-packages/notfound/__pycache__/extension.cpython-310.pyc
./venv-3.14/lib/python3.10/site-packages/notfound/__pycache__/utils.cpython-310.pyc
./venv-3.14/lib/python3.10/site-packages/notfound/__init__.py
./venv-3.14/lib/python3.10/site-packages/notfound/extension.py
./venv-3.14/lib/python3.10/site-packages/notfound/utils.py

I'm not sure what's up, perhaps it's some Nginx config?

But at least it is useful on the previews, and there is a plan to host the docs on Read the Docs: python/docs-community#5.

[AA-Turner]

It's because the prefix defaults to /en/latest.

Ideally there would be a way to define this via a pattern (e.g. /{language}/{version}/), but currently it is only a static string.

We can't use that static string because we don't know the language ahead of time though, as we use -D language=XX on the command line. So I don't see a good way of resolving this.

A

[hugovk]

It's useful for RTD previews, so I suggest we either leave it be, or only install it for RTD builds.

It's not a heavy dependency, so I lean towards leaving it be.

[nineteendo]

We can't use that static string because we don't know the language ahead of time though, as we use -D language=XX on the command line.

Can't you use an environment variable, as those can be retrieved in conf.py.

[m-aciek]

if not os.getenv("READTHEDOCS"):
    notfound_urls_prefix = '/3/'

in conf.py should help here. The links will be able to fetch the static resources just fine, no matter if the nginx error_page directives will be set per build or globally. Please see #139386.

[m-aciek]

My PR with above change has been closed. I think it should be reopened and merged, as a 404 page linking to stable version of docs on all paths that would end with 404 is better than the standard raw nginx 404 page.

We can track improvements for 404 pages per language and version in follow-ups.

[AA-Turner]

I appreciate it looks nicer, but semantically it is the wrong thing to do to redirect a user from e.g. /fr/3.8/le_spam.html to /3/404.html. If the notfound page extension adds support for template substitutions, I'd be happy to revisit it, but we shouldn't make the wrong change here.

A

[m-aciek]

I've added a feature request in sphinx-notfound-page for substitution of language. Apparently there's no need for substitution of version as we already have it in conf.py.