Documentation 404 pages are broken

[gotmax23]

404 pages are currently quite broken. Navigate to any arbitrary URL (e.g., https://docs.ansible.com/ansible/latest/xxjxjx), and you'll get an unformatted HTML page with random text. There used to be a proper 404 page with a cowsay image, but it seems that broke some time ago.

[gotmax23]

9d4c6db fixes part of the problem, but there's still broken stylesheet links in the header:

<!-- _build/html/404.html from make coredocs -->
      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/pygments.css', priority=200, rel='stylesheet', type='text/css')" type="text/css" />
      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/css/ansible.css', priority=200, rel='stylesheet', type='text/css')" type="text/css" />
      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/antsibull-minimal.css', priority=500, rel='stylesheet', type='text/css')" type="text/css" />
      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/css/rtd-ethical-ads.css', priority=500, rel='stylesheet', type='text/css')" type="text/css" />
      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/css/core-color-scheme.css', priority=800, rel='stylesheet', type='text/css')" type="text/css" />

vs. the following in a correctly formatted page:

<!-- _build/html/index.html from make coredocs -->
      <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
      <link rel="stylesheet" href="_static/css/ansible.css" type="text/css" />
      <link rel="stylesheet" href="_static/antsibull-minimal.css" type="text/css" />
      <link rel="stylesheet" href="_static/css/rtd-ethical-ads.css" type="text/css" />
      <link rel="stylesheet" href="_static/css/core-color-scheme.css" type="text/css" />

[gotmax23]

@felixfontein, @webknjaz, any idea what's going on here? You know more about the Sphinx stuff than I do.

[webknjaz]

Well, Sphinx is a static site generator. If you end up on a URL that doesn't have a stub page, whatever webserver you use will use its own 404. Though, relative links are hard regardless, in this case.

[webknjaz]

Is your problem that _CascadingStyleSheet gets rendered as text?

[felixfontein]

A similar issue was reported here recently: readthedocs/sphinx-notfound-page#224

I also had this problem (_CascadingStyleSheet showing up in the HTML file) a bit earlier today, but then I wasn't able to reproduce it.

Do you have a way to reproduce this @gotmax23?

[felixfontein]

(And yes, 9d4c6db is definitely needed. Can you create a PR for it?)

[gotmax23]

Well, Sphinx is a static site generator. If you end up on a URL that doesn't have a stub page, whatever webserver you use will use its own 404.

Right, but we use sphinx-notfound-page to generate a 404 page that's served by the webserver when a path is not found.

Is your problem that _CascadingStyleSheet gets rendered as text?

Yes.

Do you have a way to reproduce this @gotmax23?

Running make coredocs and looking at the generated 404.html should be enough to reproduce it.

[gotmax23]

(And yes, 9d4c6db is definitely needed. Can you create a PR for it?)

I opened #827 as a draft.

[felixfontein]

Do you have a way to reproduce this @gotmax23?

Running make coredocs and looking at the generated 404.html should be enough to reproduce it.

After running it the first time I also got the bad links. After running make clean, manually purging the Sphinx build data, and running make coredocs again I got working links. So right now I cannot reproduce this, at least not on my system.

[gotmax23]

Are you using the pinned dependencies? The RTD builds have the same issue, and they run in a clean environment.

$ curl -s https://ansible--827.org.readthedocs.build/projects/ansible-core/en/827/404.html | grep -n _CascadingStyleSheet
8:      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/pygments.css', priority=200, rel='stylesheet', type='text/css')" type="text/css" />
9:      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/css/ansible.css', priority=200, rel='stylesheet', type='text/css')" type="text/css" />
10:      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/antsibull-minimal.css', priority=500, rel='stylesheet', type='text/css')" type="text/css" />
11:      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/copybutton.css', priority=500, rel='stylesheet', type='text/css')" type="text/css" />
12:      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/css/rtd-ethical-ads.css', priority=500, rel='stylesheet', type='text/css')" type="text/css" />
13:      <link rel="stylesheet" href="/ansible/latest/_CascadingStyleSheet('_static/css/core-color-scheme.css', priority=800, rel='stylesheet', type='text/css')" type="text/css" />

[felixfontein]

No, I used the dev versions of the packages I had installed locally.

I did some more digging. Upgrading sphinx_rtd_theme from 1.3.0 to 2.0.0rc2 helped. (2.0.0rc1 has the same problem.) When looking at the differences between 2.0.0rc1 and 2.0.0rc2 my spontaneous guess is that readthedocs/sphinx_rtd_theme#1519 fixes the problem.

So we can probably:

1. Either upgrade to a pre-release of sphinx_rtd_theme;
2. Or downgrade Sphinx to < 7.2;
3. Or wait for 2.0.0 of sphinx_rtd_theme (and keep the 404 page broken until then).

[samccann]

#3 doesn't seem a viable option since rc2 was back at the end of Aug (aka we have no real idea when the official 2.0 version will be released.

#2 seems to be the safe solution - going back to a stable set of requirements.

I could live with #1 if folks prefer that approach.

[gotmax23]

What about trying #1 on devel and #2 on stable-2.16 and stable-2.15?

[gotmax23]

What about trying #1 on devel and #2 on stable-2.16 and stable-2.15?

devel: #851
stable-2.16: #852