Contextualize 404 page

media/css/core.css

@@ -1331,6 +1331,9 @@ div.module.project-subprojects li.subproject a.subproject-edit:before {
     content: "\f044";
 }
 
+#content ul.normal_list {list-style: disc; margin-left: 20px;}
+#content code {background: #eee; border: 1px solid #ccc; padding: 3px; display: inline-block;}
+
 /* Pygments */
 div.highlight pre .hll { background-color: #ffffcc }
 div.highlight pre .c { color: #60a0b0; font-style: italic } /* Comment */

readthedocs/core/views/__init__.py

@@ -13,6 +13,13 @@
 
 from readthedocs.core.mixins import PrivateViewMixin
 from readthedocs.projects.models import Project
+from readthedocs.proxito.exceptions import (
+    ProxitoHttp404,
+    ProxitoProjectHttp404,
+    ProxitoProjectPageHttp404,
+    ProxitoProjectVersionHttp404,
+    ProxitoSubProjectHttp404,
+)
 
 log = structlog.get_logger(__name__)
 
@@ -48,6 +55,49 @@ def get_context_data(self, **kwargs):
         return context
 
 
+def server_error_404(request, template_name="errors/404/base.html", exception=None):
+    """
+    Serves a 404 error message, handling 404 exception types raised throughout the app.
+
+    Notice that handling of 404 errors happens elsewhere in views and middleware,
+    this view is expected to serve an actual 404 message.
+    """
+
+    context = {}
+    # Properties are set by ProxitoHttp404. We could also have a look at the
+    # subproject_slug
+    if isinstance(exception, ProxitoHttp404):
+        # These attributes are not guaranteed.
+        context.update(
+            {
+                "project": getattr(exception, "project", None),
+                "project_slug": getattr(exception, "project_slug", None),
+                "subproject_slug": getattr(exception, "subproject_slug", None),
+                "version_slug": getattr(exception, "version_slug", None),
+                "path_not_found": getattr(exception, "proxito_path", None),
+            }
+        )
+
+    context["path_not_found"] = context.get("path_not_found") or request.path
+
+    if isinstance(exception, ProxitoProjectVersionHttp404):
+        template_name = "errors/404/no_version.html"
+    elif isinstance(exception, ProxitoSubProjectHttp404):
+        template_name = "errors/404/no_subproject.html"
+    elif isinstance(exception, ProxitoProjectPageHttp404):
+        template_name = "errors/404/no_project_page.html"
+    elif isinstance(exception, ProxitoProjectHttp404):
+        template_name = "errors/404/no_project.html"
+
+    r = render(
+        request,
+        template_name,
+        context=context,
+    )
+    r.status_code = 404
+    return r
+
+
 def server_error_500(request, template_name='500.html'):
     """A simple 500 handler so we get media."""
     r = render(request, template_name)

readthedocs/proxito/exceptions.py

@@ -0,0 +1,86 @@
+"""
+Exceptions for El Proxito.
+
+This module contains exceptions that may be raised in El 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."""
+
+
+class ProxitoProjectHttp404(ProxitoHttp404):
+
+    """Raised if a project was not found."""
+
+    def __init__(self, message, project_slug=None, proxito_path=None):
+        self.project_slug = project_slug
+        self.proxito_path = proxito_path
+        super().__init__(message)
+
+
+class ProxitoSubProjectHttp404(ProxitoProjectHttp404):
+
+    """Raised if a subproject was not found."""
+
+    def __init__(
+        self,
+        message,
+        project_slug=None,
+        proxito_path=None,
+        project=None,
+        subproject_slug=None,
+    ):
+        super().__init__(message, project_slug=project_slug, proxito_path=proxito_path)
+        self.project = project
+        self.subproject_slug = subproject_slug
+
+
+class ProxitoProjectPageHttp404(ProxitoProjectHttp404):
+
+    """Raised if a page inside an existing project was not found."""
+
+    def __init__(
+        self,
+        message,
+        project_slug=None,
+        proxito_path=None,
+        project=None,
+        subproject_slug=None,
+    ):
+        super().__init__(message, project_slug=project_slug, proxito_path=proxito_path)
+        self.project = project
+        self.subproject_slug = subproject_slug
+
+
+class ProxitoProjectVersionHttp404(ProxitoProjectHttp404):
+
+    """
+    Raised if a version 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,
+        proxito_path=None,
+        project=None,
+        subproject_slug=None,
+        version_slug=None,
+    ):
+        super().__init__(message, project_slug=project_slug, proxito_path=proxito_path)
+        self.project = project
+        self.subproject_slug = subproject_slug
+        self.version_slug = version_slug

readthedocs/proxito/middleware.py

@@ -12,7 +12,6 @@
 import structlog
 from django.conf import settings
 from django.core.exceptions import SuspiciousOperation
-from django.http import Http404
 from django.shortcuts import redirect, render
 from django.urls import reverse
 from django.utils.deprecation import MiddlewareMixin
@@ -26,6 +25,7 @@
     unresolver,
 )
 from readthedocs.core.utils import get_cache_tag
+from readthedocs.proxito.exceptions import ProxitoProjectHttp404
 
 log = structlog.get_logger(__name__)
 
@@ -213,9 +213,16 @@ def process_request(self, request):  # noqa
                 context={"host": exc.domain},
                 status=400,
             )
-        except (InvalidSubdomainError, InvalidExternalDomainError):
+        except (InvalidSubdomainError, InvalidExternalDomainError) as exc:
             log.debug("Invalid project set on the subdomain.")
-            raise Http404
+            # We pass e.domain as 'project_slug' because we cannot unpack a slug from the
+            # domain at this stage. The domain can be a custom domain docs.foobar.tld,
+            # in which case 'docs' would be an incorrect slug.
+            raise ProxitoProjectHttp404(
+                f"No project found for requested domain {exc.domain}.",
+                project_slug=exc.domain,
+                proxito_path=request.path,
+            )
         except InvalidCustomDomainError as exc:
             # Some person is CNAMEing to us without configuring a domain - 404.
             log.debug("CNAME 404.", domain=exc.domain)

readthedocs/proxito/views/decorators.py

@@ -2,9 +2,12 @@
 
 import structlog
 from django.db.models import Q
-from django.http import Http404
 
 from readthedocs.projects.models import Project, ProjectRelationship
+from readthedocs.proxito.exceptions import (
+    ProxitoProjectHttp404,
+    ProxitoSubProjectHttp404,
+)
 
 log = structlog.get_logger(__name__)  # noqa
 
@@ -20,14 +23,17 @@ def map_subproject_slug(view_func):
 
     @wraps(view_func)
     def inner_view(  # noqa
-            request, subproject=None, subproject_slug=None, *args, **kwargs
+        request, subproject=None, subproject_slug=None, *args, **kwargs
     ):
+        # Something not entirely clear is happening when unpacking args and kwargs
+        # so the project is fetched from kwarg dictionary.
+        project = kwargs["project"]
         if subproject is None and subproject_slug:
             # Try to fetch by subproject alias first, otherwise we might end up
             # redirected to an unrelated project.
             # Depends on a project passed into kwargs
             rel = (
-                ProjectRelationship.objects.filter(parent=kwargs["project"])
+                ProjectRelationship.objects.filter(parent=project)
                 .filter(Q(alias=subproject_slug) | Q(child__slug=subproject_slug))
                 .first()
             )
@@ -37,9 +43,15 @@ def inner_view(  # noqa
                 log.warning(
                     "The slug is not subproject of project.",
                     subproject_slug=subproject_slug,
-                    project_slug=kwargs["project"].slug,
+                    project_slug=project.slug,
+                    project=project,
+                )
+                raise ProxitoSubProjectHttp404(
+                    "Invalid subproject slug",
+                    project_slug=project.slug,
+                    project=project,
+                    subproject_slug=subproject_slug,
                 )
-                raise Http404("Invalid subproject slug")
         return view_func(request, subproject=subproject, *args, **kwargs)
 
     return inner_view
@@ -71,7 +83,10 @@ def inner_view(  # noqa
                 try:
                     project = Project.objects.get(slug=project_slug)
                 except Project.DoesNotExist:
-                    raise Http404("Project does not exist.")
+                    log.debug(f"No project found with slug {project_slug}")
+                    raise ProxitoProjectHttp404(
+                        "Project does not exist.", project_slug=project_slug
+                    )
         return view_func(request, project=project, *args, **kwargs)
 
     return inner_view