[1.9.x] Fixed #26124 -- Added missing code formatting to docs headers.

Backport of a6ef025dfb2a1d1bd23893408eef6d066fb506d9 from master

3 files changed, 45 insertions, 22 deletions

diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt
index 4744266a47..66861be947 100644
--- a/docs/topics/auth/customizing.txt
+++ b/docs/topics/auth/customizing.txt
@@ -292,8 +292,8 @@ example, the following checks if a user may view tasks::
 
 .. _extending-user:
 
-Extending the existing User model
-=================================
+Extending the existing ``User`` model
+=====================================
 
 There are two ways to extend the default
 :class:`~django.contrib.auth.models.User` model without substituting your own
@@ -363,8 +363,8 @@ the extra database load.
 
 .. _auth-custom-user:
 
-Substituting a custom User model
-================================
+Substituting a custom ``User`` model
+====================================
 
 Some kinds of projects may have authentication requirements for which Django's
 built-in :class:`~django.contrib.auth.models.User` model is not always
@@ -417,8 +417,8 @@ use as your User model.
    :class:`~django.db.models.OneToOneField` to ``settings.AUTH_USER_MODEL``
    as described below.
 
-Referencing the User model
---------------------------
+Referencing the ``User`` model
+------------------------------
 
 .. currentmodule:: django.contrib.auth
 
@@ -465,8 +465,8 @@ different User model.
 
 .. _specifying-custom-user-model:
 
-Specifying a custom User model
-------------------------------
+Specifying a custom ``User`` model
+----------------------------------
 
 .. admonition:: Model design considerations
 
@@ -728,8 +728,8 @@ utility methods:
         * ``o``, ``O``, and ``0`` (lowercase letter o, uppercase letter o,
           and zero)
 
-Extending Django's default User
--------------------------------
+Extending Django's default ``User``
+-----------------------------------
 
 If you're entirely happy with Django's :class:`~django.contrib.auth.models.User`
 model and you just want to add some additional profile information, you could
@@ -887,16 +887,16 @@ methods and attributes:
         (the Django app label). If the user is inactive, this method will
         always return ``False``.
 
-.. admonition:: ModelBackend
+.. admonition:: ``PermissionsMixin`` and ``ModelBackend``
 
     If you don't include the
     :class:`~django.contrib.auth.models.PermissionsMixin`, you must ensure you
     don't invoke the permissions methods on ``ModelBackend``. ``ModelBackend``
-    assumes that certain fields are available on your user model. If your User
-    model doesn't provide  those fields, you will receive database errors when
-    you check permissions.
+    assumes that certain fields are available on your user model. If your
+    ``User`` model doesn't provide  those fields, you will receive database
+    errors when you check permissions.
 
-Custom users and Proxy models
+Custom users and proxy models
 -----------------------------
 
 One limitation of custom User models is that installing a custom User model
diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index e8aa63d0a6..afa8ad5204 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -17,8 +17,8 @@ are somewhat coupled.
 
 .. _user-objects:
 
-User objects
-============
+``User`` objects
+================
 
 :class:`~django.contrib.auth.models.User` objects are the core of the
 authentication system. They typically represent the people interacting with
@@ -113,7 +113,7 @@ Changing a user's password will log out all their sessions if the
 :class:`~django.contrib.auth.middleware.SessionAuthenticationMiddleware` is
 enabled. See :ref:`session-invalidation-on-password-change` for details.
 
-Authenticating Users
+Authenticating users
 --------------------
 
 .. function:: authenticate(\**credentials)
@@ -369,6 +369,29 @@ If you have an authenticated user you want to attach to the current session
     raised if you try to login a user object retrieved from the database
     directly.
 
+Selecting the authentication backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a user logs in, the user's ID and the backend that was used for
+authentication are saved in the user's session. This allows the same
+:ref:`authentication backend <authentication-backends>` to fetch the user's
+details on a future request. The authentication backend to save in the session
+is selected as follows:
+
+#. Use the value of the optional ``backend`` argument, if provided.
+#. Use the value of the ``user.backend`` attribute, if present. This allows
+   pairing :func:`~django.contrib.auth.authenticate()` and
+   :func:`~django.contrib.auth.login()`:
+   :func:`~django.contrib.auth.authenticate()`
+   sets the ``user.backend`` attribute on the ``User`` object it returns.
+#. Use the ``backend`` in :setting:`AUTHENTICATION_BACKENDS`, if there is only
+   one.
+#. Otherwise, raise an exception.
+
+In cases 1 and 2, the value of the ``backend`` argument or the ``user.backend``
+attribute should be a dotted import path string (like that found in
+:setting:`AUTHENTICATION_BACKENDS`), not the actual backend class.
+
 How to log a user out
 ---------------------
 
@@ -1679,7 +1702,7 @@ model. Groups can be created, and permissions can be assigned to users or
 groups. A log of user edits to models made within the admin is also stored and
 displayed.
 
-Creating Users
+Creating users
 --------------
 
 You should see a link to "Users" in the "Auth"
@@ -1701,7 +1724,7 @@ non-superuser the ability to edit users, this is ultimately the same as giving
 them superuser status because they will be able to elevate permissions of
 users including themselves!
 
-Changing Passwords
+Changing passwords
 ------------------
 
 User passwords are not displayed in the admin (nor stored in the database), but
diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt
index 944c81408e..ef14f7f330 100644
--- a/docs/topics/auth/passwords.txt
+++ b/docs/topics/auth/passwords.txt
@@ -74,8 +74,8 @@ setting.
 
 .. _bcrypt_usage:
 
-Using bcrypt with Django
-------------------------
+Using ``bcrypt`` with Django
+----------------------------
 
 Bcrypt_ is a popular password storage algorithm that's specifically designed
 for long-term password storage. It's not the default used by Django since it