Add the Sphinx notfound page extension

[oraNod]

SUMMARY

Add https://sphinx-notfound-page.readthedocs.io/en/latest/installation.html

This is an attempt to fix the 404 page issues on read the docs.

ISSUE TYPE

• Bug, Docs Fix or other nominal change

COMPONENT NAME

• Docs

AWX VERSION

n/a

ADDITIONAL INFORMATION

follows up on #15668

[oraNod]

I've added this to a project from my fork: https://oranod-awx.readthedocs.io/en/latest/

You can request a fake page name like foo.html and see the 404 page is there. The cowsay image is apparently getting picked up by the extension but the theme isn't applied.

[webknjaz]

Comparing https://oranod-awx.readthedocs.io/en/latest/ and https://oranod-awx.readthedocs.io/en/latest/foo.html:

- <title>Ansible AWX Documentation &mdash; Ansible AWX community documentation</title>
+ <title>Oh no! &mdash; Ansible AWX community documentation</title>
-       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+       <link rel="stylesheet" href="/en/latest/_CascadingStyleSheet('_static/pygments.css', priority=200, rel='stylesheet', type='text/css')" type="text/css" />
-       <link rel="stylesheet" href="_static/css/ansible.css" type="text/css" />
+       <link rel="stylesheet" href="/en/latest/_CascadingStyleSheet('_static/css/ansible.css', priority=200, rel='stylesheet', type='text/css')" type="text/css" />
-       <link rel="stylesheet" href="_static/css/rtd-ethical-ads.css" type="text/css" />
+       <link rel="stylesheet" href="/en/latest/_CascadingStyleSheet('_static/css/rtd-ethical-ads.css', priority=500, rel='stylesheet', type='text/css')" type="text/css" />
-     <link rel="shortcut icon" href="_static/images/Ansible-Mark-RGB_Black.png"/>
+     <link rel="shortcut icon" href="/en/latest/_static/images/Ansible-Mark-RGB_Black.png"/>
    <!--[if lt IE 9]>
-     <script src="_static/js/html5shiv.min.js"></script>
+     <script src="/en/latest/_static/js/html5shiv.min.js"></script>
    <![endif]-->
  
-         <script src="_static/jquery.js?v=5d32c60e"></script>
+         <script src="/en/latest/_static/jquery.js?v=5d32c60e"></script>
-         <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
+         <script src="/en/latest/_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-         <script src="_static/documentation_options.js?v=a9b6e813"></script>
+         <script src="/en/latest/_static/documentation_options.js?v=a9b6e813"></script>
-         <script src="_static/doctools.js?v=888ff710"></script>
+         <script src="/en/latest/_static/doctools.js?v=888ff710"></script>
-         <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+         <script src="/en/latest/_static/sphinx_highlight.js?v=dc90522c"></script>
-     <script src="_static/js/theme.js"></script>
+     <script src="/en/latest/_static/js/theme.js"></script>

I'm not sure why _CascadingStyleSheet() is leaking into the rendered HTML output. I think I saw this before, but never looked deep. The theme demo seems to be fine: https://sphinx-ansible-theme.readthedocs.io/en/latest/foo.html.

I think there's some incompatibility between versions of CPython, Sphinx and the underlying sphinx-rtd-theme. Somebody will probably have to bisect it.

readthedocs/sphinx-notfound-page#224 mentions the same problem and ansible/ansible-documentation#678 links ansible/ansible-documentation@9d4c6db that suggests that changing what settings are used might be the fix: https://github.com/ansible/ansible-documentation/pull/827/files#diff-de16707d76a94c258b2d4ba2b8f95910db018b923e2b4834dacf47c8964b2a90R340.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[oraNod]

Thanks for taking a look @webknjaz I completely forgot that the Ansible docs had a similar problem. I wasn't really involved in that one though so I guess it didn't stick.

I'm not sure I'll be the best at explaining why but upgrading the requirements seems to have worked. The 404 page is doing it's thing on my fork and I don't see that issue with _CascadingStyleSheet() leaking through. From what I can tell the upgrade didn't break anything - I was concerned about the API guide but that looks OK to me. Maybe when that starts getting updated we'll need to take another look.

The 404 page doesn't look right in the PR preview but I suspect that is down to the settings I added to conf.py. Anyway, you can see it in action from my fork here: https://oranod-awx.readthedocs.io/en/latest/404.html

Or this non-existent page: https://oranod-awx.readthedocs.io/en/latest/foo.html

[tvo318]

I trust the previews are accurate. Thanks for getting this done so quickly, @oraNod!

[samccann]

My brain is still on PTO but I looked at https://ansible--15669.org.readthedocs.build/projects/awx/en/15669/foo.html and it has the same formatting problem.

[oraNod]

My brain is still on PTO but I looked at https://ansible--15669.org.readthedocs.build/projects/awx/en/15669/foo.html and it has the same formatting problem.

Thanks @samccann I think this is down to the settings in conf.py that specify the path to the 404 page, which I guess doesn't exist in the preview environment. I could be wrong but it works in my fork where it did not before.

[gundalow]

CI errors (API Check) aren't related to this change

[samccann]

Why are 404pages so hard lol. So it has the correct formatting, but there is no versin flyout menu on the lower right on the custom 404 page. Rather than bang against this even more, I recommend we just change the wording to remove mention of that. The page already has a direct link to the 24.6.1 version of the docs.