[3.0.x] Fixed #31103 -- Improved pagination topic documentation.

Backport of 0f0abc20be from master

docs/topics/pagination.txt

@@ -10,8 +10,8 @@ The ``Paginator`` class
 
 Under the hood, all methods of pagination use the
 :class:`~django.core.paginator.Paginator` class. It does all the heavy lifting
-of actually splitting a ``QuerySet`` into parts and handing them over to other
-components.
+of actually splitting a ``QuerySet`` into :class:`~django.core.paginator.Page`
+objects.
 
 Example
 =======
@@ -82,52 +82,25 @@ Paginating a ``ListView``
 =========================
 
 :class:`django.views.generic.list.ListView` provides a builtin way to paginate
-the displayed list. You can do this by adding
+the displayed list. You can do this by adding a
 :attr:`~django.views.generic.list.MultipleObjectMixin.paginate_by` attribute to
 your view class, for example::
 
     from django.views.generic import ListView
 
-    from myapp.models import Contacts
+    from myapp.models import Contact
 
-    class ContactsList(ListView):
+    class ContactList(ListView):
         paginate_by = 2
-        model = Contacts
+        model = Contact
 
-The only thing your users will be missing is a way to navigate to the next or
-previous page. To achieve this, add links to the next and previous page, like
-shown in the below example ``list.html``.
-
-.. _using-paginator-in-view:
-
-Using ``Paginator`` in a view
-=============================
-
-Here's a slightly more complex example using
-:class:`~django.core.paginator.Paginator` in a view to paginate a queryset. We
-give both the view and the accompanying template to show how you can display
-the results. This example assumes you have a ``Contacts`` model that has
-already been imported.
-
-The view function looks like this::
-
-    from django.core.paginator import Paginator
-    from django.shortcuts import render
-
-    def listing(request):
-        contact_list = Contacts.objects.all()
-        paginator = Paginator(contact_list, 25) # Show 25 contacts per page
-
-        page = request.GET.get('page')
-        contacts = paginator.get_page(page)
-        return render(request, 'list.html', {'contacts': contacts})
-
-In the template :file:`list.html`, you'll want to include navigation between
-pages along with any interesting information from the objects themselves:
+This limits the number of objects per page and adds a ``paginator`` and
+``page_obj`` to the ``context``. To allow your users to navigate between pages,
+add links to the next and previous page, in your template like this:
 
 .. code-block:: html+django
 
-    {% for contact in contacts %}
+    {% for contact in page_obj %}
         {# Each "contact" is a Contact model object. #}
         {{ contact.full_name|upper }}<br>
         ...
@@ -135,18 +108,42 @@ pages along with any interesting information from the objects themselves:
 
     <div class="pagination">
         <span class="step-links">
-            {% if contacts.has_previous %}
+            {% if page_obj.has_previous %}
                 <a href="?page=1">&laquo; first</a>
-                <a href="?page={{ contacts.previous_page_number }}">previous</a>
+                <a href="?page={{ page_obj.previous_page_number }}">previous</a>
             {% endif %}
 
             <span class="current">
-                Page {{ contacts.number }} of {{ contacts.paginator.num_pages }}.
+                Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}.
             </span>
 
-            {% if contacts.has_next %}
-                <a href="?page={{ contacts.next_page_number }}">next</a>
-                <a href="?page={{ contacts.paginator.num_pages }}">last &raquo;</a>
+            {% if page_obj.has_next %}
+                <a href="?page={{ page_obj.next_page_number }}">next</a>
+                <a href="?page={{ page_obj.paginator.num_pages }}">last &raquo;</a>
             {% endif %}
         </span>
     </div>
+
+.. _using-paginator-in-view:
+
+Using ``Paginator`` in a view function
+======================================
+
+Here's an example using :class:`~django.core.paginator.Paginator` in a view
+function to paginate a queryset::
+
+    from django.core.paginator import Paginator
+    from django.shortcuts import render
+
+    from myapp.models import Contact
+
+    def listing(request):
+        contact_list = Contact.objects.all()
+        paginator = Paginator(contact_list, 25) # Show 25 contacts per page.
+
+        page_number = request.GET.get('page')
+        page_obj = paginator.get_page(page_number)
+        return render(request, 'list.html', {'page_obj': page_obj})
+
+In the template :file:`list.html`, you can include navigation between pages in
+the same way as in the template for the ``ListView`` above.