Fixed #21938 -- Moved documentation for error views to reference guide.

docs/ref/views.txt

@@ -9,7 +9,7 @@ Several of Django's built-in views are documented in
 :doc:`/topics/http/views` as well as elsewhere in the documentation.
 
 Serving files in development
-----------------------------
+============================
 
 .. function:: static.serve(request, path, document_root, show_indexes=False)
 
@@ -47,3 +47,104 @@ ships with a small URL helper function :func:`~django.conf.urls.static.static`
 that takes as parameters the prefix such as :setting:`MEDIA_URL` and a dotted
 path to a view, such as ``'django.views.static.serve'``. Any other function
 parameter will be transparently passed to the view.
+
+.. _error-views:
+
+Error views
+===========
+
+Django comes with a few views by default for handling HTTP errors. To override
+these with your own custom views, see :ref:`customizing-error-views`.
+
+.. _http_not_found_view:
+
+The 404 (page not found) view
+-----------------------------
+
+.. function:: defaults.page_not_found(request, template_name='404.html')
+
+When you raise :exc:`~django.http.Http404` from within a view, Django loads a
+special view devoted to handling 404 errors. By default, it's the view
+:func:`django.views.defaults.page_not_found`, which either produces a very
+simple "Not Found" message or loads and renders the template ``404.html`` if
+you created it in your root template directory.
+
+The default 404 view will pass one variable to the template: ``request_path``,
+which is the URL that resulted in the error.
+
+Three things to note about 404 views:
+
+* The 404 view is also called if Django doesn't find a match after
+  checking every regular expression in the URLconf.
+
+* The 404 view is passed a :class:`~django.template.RequestContext` and
+  will have access to variables supplied by your
+  :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting (e.g., ``MEDIA_URL``).
+
+* If :setting:`DEBUG` is set to ``True`` (in your settings module), then
+  your 404 view will never be used, and your URLconf will be displayed
+  instead, with some debug information.
+
+.. _http_internal_server_error_view:
+
+The 500 (server error) view
+---------------------------
+
+.. function:: defaults.server_error(request, template_name='500.html')
+
+Similarly, Django executes special-case behavior in the case of runtime errors
+in view code. If a view results in an exception, Django will, by default, call
+the view ``django.views.defaults.server_error``, which either produces a very
+simple "Server Error" message or loads and renders the template ``500.html`` if
+you created it in your root template directory.
+
+The default 500 view passes no variables to the ``500.html`` template and is
+rendered with an empty ``Context`` to lessen the chance of additional errors.
+
+If :setting:`DEBUG` is set to ``True`` (in your settings module), then
+your 500 view will never be used, and the traceback will be displayed
+instead, with some debug information.
+
+.. _http_forbidden_view:
+
+The 403 (HTTP Forbidden) view
+-----------------------------
+
+.. function:: defaults.permission_denied(request, template_name='403.html')
+
+In the same vein as the 404 and 500 views, Django has a view to handle 403
+Forbidden errors. If a view results in a 403 exception then Django will, by
+default, call the view ``django.views.defaults.permission_denied``.
+
+This view loads and renders the template ``403.html`` in your root template
+directory, or if this file does not exist, instead serves the text
+"403 Forbidden", as per :rfc:`2616` (the HTTP 1.1 Specification).
+
+``django.views.defaults.permission_denied`` is triggered by a
+:exc:`~django.core.exceptions.PermissionDenied` exception. To deny access in a
+view you can use code like this::
+
+    from django.core.exceptions import PermissionDenied
+
+    def edit(request, pk):
+        if not request.user.is_staff:
+            raise PermissionDenied
+        # ...
+
+.. _http_bad_request_view:
+
+The 400 (bad request) view
+--------------------------
+
+.. function:: defaults.bad_request(request, template_name='400.html')
+
+When a :exc:`~django.core.exceptions.SuspiciousOperation` is raised in Django,
+it may be handled by a component of Django (for example resetting the session
+data). If not specifically handled, Django will consider the current request a
+'bad request' instead of a server error.
+
+``django.views.defaults.bad_request``, is otherwise very similar to the
+``server_error`` view, but returns with the status code 400 indicating that
+the error condition was the result of a client operation.
+
+``bad_request`` views are also only used when :setting:`DEBUG` is ``False``.

docs/topics/http/views.txt

@@ -133,128 +133,27 @@ called ``404.html`` and located in the top level of your template tree.
 Customizing error views
 =======================
 
-.. _http_not_found_view:
+The default error views in Django should suffice for most Web applications,
+but can easily be overridden if you need any custom behavior. Simply specify
+the handlers as seen below in your URLconf (setting them anywhere else will
+have no effect).
 
-The 404 (page not found) view
------------------------------
+The :func:`~django.views.defaults.page_not_found` view is overridden by
+:data:`~django.conf.urls.handler404`::
 
-.. function:: django.views.defaults.page_not_found(request, template_name='404.html')
+    handler404 = 'mysite.views.my_custom_page_not_found_view'
 
-When you raise :exc:`~django.http.Http404` from within a view, Django loads a
-special view devoted to handling 404 errors. By default, it's the view
-:func:`django.views.defaults.page_not_found`, which either produces a very
-simple "Not Found" message or loads and renders the template ``404.html`` if
-you created it in your root template directory.
-
-The default 404 view will pass one variable to the template: ``request_path``,
-which is the URL that resulted in the error.
-
-The ``page_not_found`` view should suffice for 99% of Web applications, but if
-you want to override it, you can specify :data:`~django.conf.urls.handler404`
-in your root URLconf (setting ``handler404`` anywhere else will have no
-effect), like so::
-
-    handler404 = 'mysite.views.my_custom_404_view'
-
-Behind the scenes, Django determines the 404 view by looking for
-``handler404`` in your root URLconf, and falling back to
-``django.views.defaults.page_not_found`` if you did not define one.
-
-Three things to note about 404 views:
-
-* The 404 view is also called if Django doesn't find a match after
-  checking every regular expression in the URLconf.
-
-* The 404 view is passed a :class:`~django.template.RequestContext` and
-  will have access to variables supplied by your
-  :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting (e.g., ``MEDIA_URL``).
-
-* If :setting:`DEBUG` is set to ``True`` (in your settings module), then
-  your 404 view will never be used, and your URLconf will be displayed
-  instead, with some debug information.
-
-.. _http_internal_server_error_view:
-
-The 500 (server error) view
-----------------------------
-
-.. function:: django.views.defaults.server_error(request, template_name='500.html')
-
-Similarly, Django executes special-case behavior in the case of runtime errors
-in view code. If a view results in an exception, Django will, by default, call
-the view ``django.views.defaults.server_error``, which either produces a very
-simple "Server Error" message or loads and renders the template ``500.html`` if
-you created it in your root template directory.
-
-The default 500 view passes no variables to the ``500.html`` template and is
-rendered with an empty ``Context`` to lessen the chance of additional errors.
-
-This ``server_error`` view should suffice for 99% of Web applications, but if
-you want to override the view, you can specify
-:data:`~django.conf.urls.handler500` in your root URLconf, like so::
+The :func:`~django.views.defaults.server_error` view is overridden by
+:data:`~django.conf.urls.handler500`::
 
     handler500 = 'mysite.views.my_custom_error_view'
 
-Behind the scenes, Django determines the 500 view by looking for
-``handler500`` in your root URLconf, and falling back to
-``django.views.defaults.server_error`` if you did not define one.
-
-If :setting:`DEBUG` is set to ``True`` (in your settings module), then
-your 500 view will never be used, and the traceback will be displayed
-instead, with some debug information.
-
-.. _http_forbidden_view:
-
-The 403 (HTTP Forbidden) view
------------------------------
-
-.. function:: django.views.defaults.permission_denied(request, template_name='403.html')
-
-In the same vein as the 404 and 500 views, Django has a view to handle 403
-Forbidden errors. If a view results in a 403 exception then Django will, by
-default, call the view ``django.views.defaults.permission_denied``.
-
-This view loads and renders the template ``403.html`` in your root template
-directory, or if this file does not exist, instead serves the text
-"403 Forbidden", as per :rfc:`2616` (the HTTP 1.1 Specification).
-
-``django.views.defaults.permission_denied`` is triggered by a
-:exc:`~django.core.exceptions.PermissionDenied` exception. To deny access in a
-view you can use code like this::
-
-    from django.core.exceptions import PermissionDenied
-
-    def edit(request, pk):
-        if not request.user.is_staff:
-            raise PermissionDenied
-        # ...
-
-It is possible to override ``django.views.defaults.permission_denied`` in the
-same way you can for the 404 and 500 views by specifying a
-:data:`~django.conf.urls.handler403` in your root URLconf::
+The :func:`~django.views.defaults.permission_denied` view is overridden by
+:data:`~django.conf.urls.handler403`::
 
     handler403 = 'mysite.views.my_custom_permission_denied_view'
 
-.. _http_bad_request_view:
-
-The 400 (bad request) view
---------------------------
-
-.. function:: django.views.defaults.bad_request(request, template_name='400.html')
-
-When a :exc:`~django.core.exceptions.SuspiciousOperation` is raised in Django,
-it may be handled by a component of Django (for example resetting the session
-data). If not specifically handled, Django will consider the current request a
-'bad request' instead of a server error.
-
-``django.views.defaults.bad_request``, is otherwise very similar to the
-``server_error`` view, but returns with the status code 400 indicating that
-the error condition was the result of a client operation.
-
-Like ``server_error``, the default ``bad_request`` should suffice for
-99% of Web applications, but if you want to override the view, you can specify
-:data:`~django.conf.urls.handler400` in your root URLconf, like so::
+The :func:`~django.views.defaults.bad_request` view is overridden by
+:data:`~django.conf.urls.handler400`::
 
     handler400 = 'mysite.views.my_custom_bad_request_view'
-
-``bad_request`` views are also only used when :setting:`DEBUG` is ``False``.