Contextualize 404 page

readthedocs/core/views/__init__.py

@@ -48,17 +48,25 @@ def get_context_data(self, **kwargs):
         return context
 
 
-def server_error_404(request, template_name="404.html", exception=None):
+def server_error_404(
+    request, template_name="errors/404/community.html", exception=None
+):
     """A simple 404 handler."""
     # This property is set by ProxitoHttp404. We could also have a look at the
     # subproject_slug
+
     project_slug = getattr(exception, "project_slug", None)
     log.debug(exception)
     project = getattr(exception, "project", None)
-    log.debug(
-        "404 page detected a project slug in request.",
-        project_slug=project_slug,
-    )
+    subproject_slug = getattr(exception, "subproject_slug", None)
+
+    if subproject_slug:
+        template_name = "errors/404/no_subproject.html"
+    elif project:
+        template_name = "errors/404/no_project_page.html"
+    elif project_slug:
+        template_name = "errors/404/no_project.html"
+
     r = render(
         request,
         template_name,

readthedocs/proxito/exceptions.py

@@ -1,7 +1,54 @@
+"""
+This module contains exceptions that may be raised in the proxito application
+but are handled elsewhere in the Django project.
+
+--------------
+404 exceptions
+--------------
+
+Because an Http404 can be raised anywhere in the code,
+we want to add more context for targeted error handling and user-facing communication
+"""
 from django.http.response import Http404
 
 
 class ProxitoHttp404(Http404):
+    """
+    General error class for proxity 404s
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+class ProxitoProjectHttp404(ProxitoHttp404):
+    """
+    Raised if a project was not found
+    """
+
+    def __init__(self, message, project_slug=None):
+        self.project_slug = project_slug
+        super().__init__(message)
+
+
+class ProxitoSubProjectHttp404(ProxitoProjectHttp404):
+    """
+    Raised if a sub-project was not found
+    """
+    def __init__(self, message, project_slug=None, project=None, subproject_slug=None):
+        self.project_slug = project_slug
+        self.project = project
+        self.subproject_slug = subproject_slug
+        super().__init__(message)
+
+
+class ProxitoProjectPageHttp404(ProxitoHttp404):
+    """
+    Raised if a page inside an existing project was not found
+
+    Note: The containing project can be both a project or a subproject inside another project
+    """
+
     def __init__(self, message, project_slug=None, project=None, subproject_slug=None):
         self.project_slug = project_slug
         self.project = project

readthedocs/templates/401.html

@@ -1,20 +1,11 @@
-{% extends "base.html" %}
+{% extends "errors/base.html" %}
 {% load core_tags %}
 {% load i18n %}
 
 {% block title %}
   {% trans "Maze Found" %}
 {% endblock %}
 
-{% block header-wrapper %}
-  {% include "error_header.html" %}
-{% endblock %}
-
-{% block notify %}{% endblock %}
-
-{# Hide the language select form so we don't set a CSRF cookie #}
-{% block language-select-form %}{% endblock %}
-
 {% block content %}
 <h3>Permission Denied</h3>
 <p>

readthedocs/templates/404.html

@@ -1,84 +1,2 @@
-{% extends "base.html" %}
-{% load core_tags %}
-{% load i18n %}
-
-{% block title %}
-  {% trans "404 - Maze Found" %}
-{% endblock %}
-
-{% block header-wrapper %}
-  {% include "error_header.html" %}
-{% endblock %}
-
-{% block notify %}{% endblock %}
-
-{# Hide the language select form so we don't set a CSRF cookie #}
-{% block language-select-form %}{% endblock %}
-
-{% block content %}
-
-<h1>{% trans "404 - page not found" %}</h1>
-
-{% if project %}
-
-  {# project exists #}
-
-  <p>
-    {% blocktrans with project_slug=project.slug request_path=request.path %}You are browsing the documentation of "{{ project_slug }}". The page you are looking for at <code>{{ request.path }}</code> was not found.{% endblocktrans %}
-  </p>
-
-  <p>
-    {% blocktrans %}Documentation changes over time. Pages are moved around. You can try to navigate to <a href="/">the index page</a> of the project and use its navigation or search function to find a similar page.{% endblocktrans %}</p>
-
-  <h3>{% trans "Are you the project owner?" %}</h3>
-
-  <p>{% trans "Here are some tips to address 404 errors:" %}</p>
-
-  <ul>
-    <li>{% trans "Use custom 404 pages:" %} <a href="https://docs.readthedocs.io/en/latest/hosting.html#custom-not-found-404-pages">{% trans "Read more" %}»</a></li>
-    <li>{% trans "Create redirects when you move contents:" %} <a href="https://docs.readthedocs.io/en/stable/user-defined-redirects.html">{% trans "Read more" %}»</a></li>
-    <li>{% trans "Use rediraffe to manage redirects in Sphinx:" %} <a href="https://pypi.org/project/sphinxext-rediraffe/">{% trans "Read more" %}»</a></li>
-  </ul>
-
-{% elif "_proxito_404_" in request.path %}
-
-  {# we are looking at a 404 generated by proxito, we then know that the project itself doesn't exist or hasn't been built #}
-
-  <p>
-    {% blocktrans with project_slug=project_slug %}The project "{{ project_slug }}" that you are looking for either does not exist, has been deleted or does not yet have any valid builds.{% endblocktrans %}
-  </p>
-
-{% else %}
-
-  <p>{% trans "You have encountered a 404 on Read the Docs. You are either looking for a page that does not exist or a project that has been removed." %}</p>
-
-  <p>{% trans "If you believe this is a technical error, please contact our support:" %} <a href="{% url 'support' %}">{% trans "Go to support" %}»</a></p>
-
-{% endif %}
-
-<pre style="line-height: 1.25; white-space: pre;">
-
-        \          SORRY            /
-         \                         /
-          \    This page does     /
-           ]   not exist yet.    [    ,'|
-           ]                     [   /  |
-           ]___               ___[ ,'   |
-           ]  ]\             /[  [ |:   |
-           ]  ] \           / [  [ |:   |
-           ]  ]  ]         [  [  [ |:   |
-           ]  ]  ]__     __[  [  [ |:   |
-           ]  ]  ] ]\ _ /[ [  [  [ |:   |
-           ]  ]  ] ] (#) [ [  [  [ :===='
-           ]  ]  ]_].nHn.[_[  [  [
-           ]  ]  ]  HHHHH. [  [  [
-           ]  ] /   `HH("N  \ [  [
-           ]__]/     HHH  "  \[__[
-           ]         NNN         [
-           ]         N/"         [
-           ]         N H         [
-          /          N            \
-         /           q,            \
-        /                           \
-</pre>
-{% endblock %}
+{% extends "errors/404/base.html" %}
+{# this is a deprecated template, will be removed. Please use one of the targeted 404s in templates/404/ #}

readthedocs/templates/429.html

@@ -1,20 +1,11 @@
-{% extends "base.html" %}
+{% extends "errors/base.html" %}
 {% load core_tags %}
 {% load i18n %}
 
 {% block title %}
   {% trans "Too many requests" %}
 {% endblock %}
 
-{% block header-wrapper %}
-  {% include "error_header.html" %}
-{% endblock %}
-
-{% block notify %}{% endblock %}
-
-{# Hide the language select form so we don't set a CSRF cookie #}
-{% block language-select-form %}{% endblock %}
-
 {% block content %}
 <pre style="line-height: 1.25; white-space: pre;">
               .--~~,__

readthedocs/templates/500.html

@@ -1,19 +1,10 @@
-{% extends "base.html" %}
+{% extends "errors/base.html" %}
 {% load i18n %}
 
 {% block title %}
   {% trans "Server Error" %}
 {% endblock %}
 
-{% block header-wrapper %}
-  {% include "error_header.html" %}
-{% endblock %}
-
-{% block notify %}{% endblock %}
-
-{# Hide the language select form so we don't set a CSRF cookie #}
-{% block language-select-form %}{% endblock %}
-
 {% block content %}
 <pre style="line-height: 1.25; white-space: pre;">
           .

readthedocs/templates/error_header.html

@@ -1,4 +1,5 @@
 {% load i18n %}
+{# this template is deprecated, please extend from errors/base.html #}
 
     <div id="rtfd-header">
       <div class="wrapper">

readthedocs/templates/errors/404/base.html

@@ -0,0 +1,50 @@
+{% extends "errors/base.html" %}
+{% load core_tags %}
+{% load i18n %}
+
+{% block title %}
+  {% trans "404 - Maze Found" %}
+{% endblock %}
+
+{% block content %}
+
+<h1>{% trans "404 - page not found" %}</h1>
+
+{% block 404_error_message %}
+
+{% endblock %}
+
+{% if project %}
+
+{% elif "_proxito_404_" in request.path %}
+
+{% else %}
+
+{% endif %}
+
+<pre style="line-height: 1.25; white-space: pre;">
+
+        \          SORRY            /
+         \                         /
+          \    This page does     /
+           ]   not exist yet.    [    ,'|
+           ]                     [   /  |
+           ]___               ___[ ,'   |
+           ]  ]\             /[  [ |:   |
+           ]  ] \           / [  [ |:   |
+           ]  ]  ]         [  [  [ |:   |
+           ]  ]  ]__     __[  [  [ |:   |
+           ]  ]  ] ]\ _ /[ [  [  [ |:   |
+           ]  ]  ] ] (#) [ [  [  [ :===='
+           ]  ]  ]_].nHn.[_[  [  [
+           ]  ]  ]  HHHHH. [  [  [
+           ]  ] /   `HH("N  \ [  [
+           ]__]/     HHH  "  \[__[
+           ]         NNN         [
+           ]         N/"         [
+           ]         N H         [
+          /          N            \
+         /           q,            \
+        /                           \
+</pre>
+{% endblock %}

readthedocs/templates/errors/404/community.html

@@ -0,0 +1,12 @@
+{% extends "errors/404/base.html" %}
+{% load i18n %}
+
+{# something on readthedocs.org does not exist - this 404 is not intended for projects #}
+
+{% block 404_error_message %}
+
+  <p>{% trans "You have encountered a 404 on Read the Docs. You are either looking for a page that does not exist or a project that has been removed." %}</p>
+
+  <p>{% trans "If you believe this is a technical error, please contact our support:" %} <a href="{% url 'support' %}">{% trans "Go to support" %}»</a></p>
+
+{% endblock %}

readthedocs/templates/errors/404/include_tips.html

@@ -0,0 +1,11 @@
+{% load i18n %}
+
+<h3>{% trans "Are you the project owner?" %}</h3>
+
+<p>{% trans "Here are some tips to address 404 errors:" %}</p>
+
+<ul>
+  <li>{% trans "Use custom 404 pages:" %} <a href="https://docs.readthedocs.io/en/latest/hosting.html#custom-not-found-404-pages">{% trans "Read more" %}»</a></li>
+  <li>{% trans "Create redirects when you move contents:" %} <a href="https://docs.readthedocs.io/en/stable/user-defined-redirects.html">{% trans "Read more" %}»</a></li>
+  <li>{% trans "Use rediraffe to manage redirects in Sphinx:" %} <a href="https://pypi.org/project/sphinxext-rediraffe/">{% trans "Read more" %}»</a></li>
+</ul>

readthedocs/templates/errors/404/no_project.html

@@ -0,0 +1,16 @@
+{% extends "errors/404/base.html" %}
+{% load i18n %}
+
+{# visiting a slug or subdomain that doesn't match the intended project #}
+
+{% block 404_error_message %}
+
+  {# we are looking at a 404 generated by proxito, we then know that the project itself doesn't exist or hasn't been built #}
+
+  <p>
+    {% blocktrans trimmed with project_slug=project_slug %}
+      The project "{{ project_slug }}" that you are looking for either does not exist, has been deleted or does not yet have any valid builds.
+    {% endblocktrans %}
+  </p>
+
+{% endblock %}

readthedocs/templates/errors/404/no_project_page.html

@@ -0,0 +1,22 @@
+{% extends "errors/404/base.html" %}
+{% load i18n %}
+
+{# project exists but page doesn't #}
+
+{% block 404_error_message %}
+
+  <p>
+    {% blocktrans trimmed with project_slug=project.slug request_path=request.path %}
+      You are browsing the documentation of "{{ project_slug }}". The page you are looking for at <code>{{ request.path }}</code> was not found.
+    {% endblocktrans %}
+  </p>
+
+  <p>
+    {% blocktrans trimmed %}
+      Documentation changes over time. Pages are moved around. You can try to navigate to <a href="/">the index page</a> of the project and use its navigation or search function to find a similar page.
+    {% endblocktrans %}
+  </p>
+
+  {% include "errors/404/include_tips.html" %}
+
+{% endblock %}

readthedocs/templates/errors/404/no_subproject.html

@@ -0,0 +1,22 @@
+{% extends "errors/404/base.html" %}
+{% load i18n %}
+
+{# project exists but page doesn't #}
+
+{% block 404_error_message %}
+
+  <p>
+    {% blocktrans trimmed with project_slug=project.slug request_path=request.path %}
+      You are browsing the documentation of "{{ project_slug }}". The page you are looking for at <code>{{ request.path }}</code> was not found.
+    {% endblocktrans %}
+  </p>
+
+  <p>
+    {% blocktrans trimmed %}
+      Documentation changes over time. Pages are moved around. You can try to navigate to <a href="/">the index page</a> of the project and use its navigation or search function to find a similar page.
+    {% endblocktrans %}
+  </p>
+
+  {% include "errors/404/include_tips.html" %}
+
+{% endblock %}