Add the Sphinx notfound page extension (#15669)

* add sphinx notfound extension
* add notfound conf
* upgrade requirements
* use double backticks
* add urls prefix

docs/docsite/conf.py

@@ -35,9 +35,13 @@ extensions = [
     'sphinx.ext.coverage',
     'sphinx.ext.ifconfig',
     'sphinx_ansible_theme',
+    'notfound.extension',
     'swagger',
 ]
 
+notfound_urls_prefix = "/en/latest/"
+notfound_template = "404.rst"
+
 html_theme = 'sphinx_ansible_theme'
 html_theme_path = ["_static"]
 

docs/docsite/requirements.in

@@ -2,6 +2,7 @@
 
 sphinx # Tooling to build HTML from RST source.
 sphinx-ansible-theme # Ansible community theme for Sphinx doc builds.
+sphinx-notfound-page # Sphinx extension for custom 404 page.
 docutils # Tooling for RST processing and the swagger extension.
-Jinja2 # Requires investiation. Possibly inherited from previous repo with a custom theme.
+Jinja2 # Requires investigation. Possibly inherited from previous repo with a custom theme.
 PyYaml # Requires investigation. Possibly used as tooling for swagger API reference content.

docs/docsite/requirements.txt

@@ -4,71 +4,69 @@
 #
 #    pip-compile --allow-unsafe --output-file=docs/docsite/requirements.txt --strip-extras docs/docsite/requirements.in
 #
-alabaster==0.7.13
+alabaster==1.0.0
     # via sphinx
 ansible-pygments==0.1.1
     # via sphinx-ansible-theme
-babel==2.13.1
+babel==2.16.0
     # via sphinx
-certifi==2023.7.22
+certifi==2024.8.30
     # via requests
-charset-normalizer==3.3.2
+charset-normalizer==3.4.0
     # via requests
-docutils==0.18.1
+docutils==0.21.2
     # via
-    #   -r requirements.in
+    #   -r docs/docsite/requirements.in
     #   sphinx
     #   sphinx-rtd-theme
-idna==3.4
+idna==3.10
     # via requests
 imagesize==1.4.1
     # via sphinx
 jinja2==3.1.4
     # via
-    #   -r requirements.in
+    #   -r docs/docsite/requirements.in
     #   sphinx
-markupsafe==2.1.3
+markupsafe==3.0.2
     # via jinja2
-packaging==23.2
+packaging==24.2
     # via sphinx
-pygments==2.16.1
+pygments==2.18.0
     # via
     #   ansible-pygments
     #   sphinx
-pyyaml==6.0.1
+pyyaml==6.0.2
-    # via -r requirements.in
+    # via -r docs/docsite/requirements.in
-requests==2.31.0
+requests==2.32.3
     # via sphinx
 snowballstemmer==2.2.0
     # via sphinx
-sphinx==7.2.6
+sphinx==8.1.3
     # via
-    #   -r requirements.in
+    #   -r docs/docsite/requirements.in
     #   sphinx-ansible-theme
+    #   sphinx-notfound-page
     #   sphinx-rtd-theme
-    #   sphinxcontrib-applehelp
-    #   sphinxcontrib-devhelp
-    #   sphinxcontrib-htmlhelp
     #   sphinxcontrib-jquery
-    #   sphinxcontrib-qthelp
+sphinx-ansible-theme==0.10.3
-    #   sphinxcontrib-serializinghtml
+    # via -r docs/docsite/requirements.in
-sphinx-ansible-theme==0.10.2
+sphinx-notfound-page==1.0.4
-    # via -r requirements.in
+    # via -r docs/docsite/requirements.in
-sphinx-rtd-theme==1.3.0
+sphinx-rtd-theme==3.0.2
     # via sphinx-ansible-theme
-sphinxcontrib-applehelp==1.0.7
+sphinxcontrib-applehelp==2.0.0
     # via sphinx
-sphinxcontrib-devhelp==1.0.5
+sphinxcontrib-devhelp==2.0.0
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.4
+sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jquery==4.1
     # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.6
+sphinxcontrib-qthelp==2.0.0
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.9
+sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
-urllib3==2.1.0
+urllib3==2.2.3
     # via requests

docs/docsite/rst/404.rst

@@ -15,5 +15,5 @@ Here is a link to the `AWX 24.6.1 <https://ansible.readthedocs.io/projects/awx/e
 If you have more questions or still can't find the docs you're looking for, join the `Ansible Forum <https://forum.ansible.com>`_.
 Here are some useful links for AWX users:
 
-* `Get Help <https://forum.ansible.com/c/help/6>`_: get help or help others. Please add appropriate tags if you start new discussions, for example `awx`, `ee`, and  `documentation`.
+* `Get Help <https://forum.ansible.com/c/help/6>`_: get help or help others. Please add appropriate tags if you start new discussions, for example ``awx``, ``ee``, and  ``documentation``.
 * `Posts tagged with 'awx' <https://forum.ansible.com/tag/awx>`_: subscribe to participate in project/technology-related conversations. There are other related tags in the forum you can use.