diff --git a/doc/source/conf.py b/doc/source/conf.py index 3c6a3994..6a61257a 100755 --- a/doc/source/conf.py +++ b/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 diff --git a/doc/source/usage.rst b/doc/source/usage.rst index fd849cfe..396685a0 100644 --- a/doc/source/usage.rst +++ b/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 +`_ 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" diff --git a/requirements/requirements_doc.txt b/requirements/requirements_doc.txt index 988467b9..94ecb427 100644 --- a/requirements/requirements_doc.txt +++ b/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 diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 65e81311..e363ef49 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/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" diff --git a/src/ansys_sphinx_theme/static/404.rst b/src/ansys_sphinx_theme/static/404.rst new file mode 100644 index 00000000..1dfd77be --- /dev/null +++ b/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 }}