Ship a basic 404 page

doc/source/conf.py

@@ -12,6 +12,7 @@
     ansys_logo_white,
     ansys_logo_white_cropped,
     latex,
+    page_404,
     watermark,
 )
 
@@ -28,6 +29,7 @@
 # specify the location of your github repo
 html_theme_options = {
     "github_url": "https://github.com/ansys/ansys-sphinx-theme",
+    "contact_mail": "pyansys.support@ansys.com",
     "additional_breadcrumbs": [
         ("Ansys Internal Developer Portal", "https://dev.docs.ansys.com"),
     ],
@@ -41,6 +43,7 @@
     "sphinx.ext.autosummary",
     "numpydoc",
     "sphinx.ext.intersphinx",
+    "notfound.extension",
     "sphinx_copybutton",
     "ansys_sphinx_theme",
 ]
@@ -99,3 +102,6 @@
 # change the preamble of latex with customized title page
 # variables are the title of pdf, watermark
 latex_elements = {"preamble": latex.generate_preamble(html_title)}
+
+# Not found page
+notfound_template = page_404

doc/source/usage.rst

@@ -186,3 +186,76 @@ import and add them in the ``latex_additional_files``:
     latex_additional_files = [
        watermark, ansys_logo_white, ansys_logo_white_cropped
     ]
+
+
+Customizing 404 page
+~~~~~~~~~~~~~~~~~~~~
+Sphinx does not support a 404 error page by default. For this reason
+`sphinx-notfound-page
+<https://sphinx-notfound-page.readthedocs.io/en/latest/index.html>`_ was
+devised.
+
+Installing and enabling ``sphinx-notfound-page``
+------------------------------------------------
+Install it by running:
+
+.. code-block:: text
+
+    python -m pip install sphinx-notfound-page
+
+Consider adding this extension to your ``requirements_doc.txt``.
+
+Using the default 404 page
+--------------------------
+Once installed, enable ``sphinx-notfound-page`` in ``conf.py`` file:
+
+.. code-block:: python
+
+    # Add the extension
+    extensions = [
+        ...,
+        "notfound.extension",
+    ]
+
+    # Add a contact mail to the theme options
+    html_theme_options = {
+        ...,
+        "contact_mail": "pyansys.support@ansys.com",
+    }
+
+To use the base 404 page provided by ``ansys-sphinx-theme``, once
+`sphinx-notfound-page`_ has been installed, add the following lines in
+``conf.py``:
+
+.. code-block:: 
+
+    from ansys_sphinx_theme import page_404
+
+
+    # Configure sphinx-notfound-page
+    notfound_template = page_404
+
+.. _sphinx-notfound-page: https://sphinx-notfound-page.readthedocs.io/en/latest/index.html
+
+Custom 404 page
+---------------
+To create a custom 404 page for your project, start by creating a ``404.rst``
+file next to ``conf.py`` file. Make sure you include the ``:orphan:`` attribute
+at the top of the ``404.rst`` page to suppress the spurious ``document isn't
+included in any toctree`` warning from Sphinx.
+
+.. code-block:: rst
+
+    :orphan:
+
+    Error 404 Not Found
+    ===================
+    The page you are requesting does not exist.
+
+Update the ``notfound_template`` variable in ``conf.py`` to the location of your
+``404.rst`` file:
+
+.. code-block:: rst
+
+    # Configure sphinx-notfound-page
+    notfound_template = "path/to/404.rst"

requirements/requirements_doc.txt

@@ -1,3 +1,4 @@
 Sphinx==5.0.2
 numpydoc==1.4.0
 sphinx-copybutton==0.5.0
+sphinx-notfound-page==0.8.3

src/ansys_sphinx_theme/__init__.py

@@ -16,6 +16,9 @@
 watermark = os.path.join(_this_path, "static", "watermark.pdf")
 ansys_logo_black = os.path.join(_this_path, "static", "ansys_logo_black_cropped.jpg")
 
+# Enable default 404 page
+page_404 = os.path.join(_this_path, "static", "404.rst")
+
 html_logo = pyansys_logo_black
 
 CSS_FILENAME = "ansys_sphinx_theme.css"

src/ansys_sphinx_theme/static/404.rst

@@ -0,0 +1,7 @@
+:orphan:
+
+Oops!
+=====
+This is unexpected. The page you are requesting does not exist.
+
+If this page should exist, please contact `{{ theme_contact_mail }} <mailto:{{ theme_contact_mail }}`_.

src/ansys_sphinx_theme/theme.conf

@@ -3,6 +3,7 @@ inherit = pydata_sphinx_theme
 pygments_style = friendly
 
 [options]
+contact_mail =
 github_url = https://github.com/ansys
 logo.link = https://www.ansys.com/
 show_breadcrumbs = True