Fixed #7781 -- Documented the per_page argument/attribute for `Pagi…

…nator` objects. Also documented `Paginator`'s other arguments and made use of ReST definition lists. Thanks to hiukkanen for the

report.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@8195 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/pagination.txt

@@ -59,30 +59,65 @@ page::
     ...
     InvalidPage
 
-Note that you can give ``Paginator`` a list/tuple, a Django ``QuerySet``, or
-any other object with a ``count()`` or ``__len__()`` method. When determining
-the number of objects contained in the passed object, ``Paginator`` will first
-try calling ``count()``, then fallback to using ``len()`` if the passed object
-has no ``count()`` method. This allows objects such as Django's ``QuerySet`` to
-use a more efficient ``count()`` method when available.
-
 ``Paginator`` objects
 =====================
 
+Required arguments
+------------------
+
+``object_list``
+    A list, tuple, Django ``QuerySet``, or other sliceable object with a
+    ``count()`` or ``__len__()`` method.
+
+``per_page``
+    The maximum number of items to include on a page, not including orphans
+    (see the ``orphans`` optional argument below).
+
+Optional arguments
+------------------
+
+``orphans``
+    The minimum number of items allowed on the last page, defaults to zero.
+    Use this when you don't want to have a last page with very few items.
+    If the last page would normally have a number of items less than or equal
+    to ``orphans``, then those items will be added to the previous page (which
+    becomes the last page) instead of leaving the items on a page by
+    themselves. For example, with 23 items, ``per_page=10``, and
+    ``orphans=3``, there will be two pages; the first page with 10 items and
+    the  second (and last) page with 13 items.
+
+``allow_empty_first_page``
+    Whether or not the first page is allowed to be empty.  If ``False`` and
+    ``object_list`` is  empty, then a ``EmptyPage`` error will be raised.
+
 Methods
 -------
 
-``page(number)`` -- Returns a ``Page`` object with the given 1-based index.
-Raises ``InvalidPage`` if the given page number doesn't exist.
+``page(number)``
+    Returns a ``Page`` object with the given 1-based index. Raises
+    ``InvalidPage`` if the given page number doesn't exist.
 
 Attributes
 ----------
 
-``count`` -- The total number of objects, across all pages.
+In addition to the arguments above, which get stored as attributes, a
+``Paginator`` object also has the following attributes:
+
+``count``
+    The total number of objects, across all pages.
+
+    **Note**: When determining the number of objects contained in
+    ``object_list``, ``Paginator`` will first try calling
+    ``object_list.count()``. If ``object_list`` has no ``count()`` method, then
+    ``Paginator`` will fallback to using ``object_list.__len__()``. This allows
+    objects, such as Django's ``QuerySet``, to use a more efficient ``count()``
+    method when available.
 
-``num_pages`` -- The total number of pages.
+``num_pages``
+    The total number of pages.
 
-``page_range`` -- A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
+``page_range``
+    A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
 
 ``InvalidPage`` exceptions
 ==========================
@@ -92,9 +127,12 @@ The ``page()`` method raises ``InvalidPage`` if the requested page is invalid
 the ``InvalidPage`` exception, but if you'd like more granularity, you can trap
 either of the following exceptions:
 
-``PageNotAnInteger`` -- Raised when ``page()`` is given a value that isn't an integer.
+``PageNotAnInteger``
+    Raised when ``page()`` is given a value that isn't an integer.
 
-``EmptyPage`` -- Raised when ``page()`` is given a valid value but no objects exist on that page.
+``EmptyPage``
+    Raised when ``page()`` is given a valid value but no objects exist on that
+    page.
 
 Both of the exceptions are subclasses of ``InvalidPage``, so you can handle
 them both with a simple ``except InvalidPage``.
@@ -105,35 +143,43 @@ them both with a simple ``except InvalidPage``.
 Methods
 -------
 
-``has_next()`` -- Returns ``True`` if there's a next page.
+``has_next()``
+    Returns ``True`` if there's a next page.
 
-``has_previous()`` -- Returns ``True`` if there's a previous page.
+``has_previous()``
+    Returns ``True`` if there's a previous page.
 
-``has_other_pages()`` -- Returns ``True`` if there's a next *or* previous page.
+``has_other_pages()``
+    Returns ``True`` if there's a next *or* previous page.
 
-``next_page_number()`` -- Returns the next page number. Note that this is
-"dumb" and will return the next page number regardless of whether a subsequent
-page exists.
+``next_page_number()``
+    Returns the next page number. Note that this is "dumb" and will return the
+    next page number regardless of whether a subsequent page exists.
 
-``previous_page_number()`` -- Returns the previous page number. Note that this
-is "dumb" and will return the previous page number regardless of whether a
-previous page exists.
+``previous_page_number()``
+    Returns the previous page number. Note that this is "dumb" and will return
+    the previous page number regardless of whether a previous page exists.
 
-``start_index()`` -- Returns the 1-based index of the first object on the page,
-relative to all of the objects in the paginator's list. For example, when
-paginating a list of 5 objects with 2 objects per page, the second page's
-``start_index()`` would return ``3``.
+``start_index()``
+    Returns the 1-based index of the first object on the page, relative to all
+    of the objects in the paginator's list. For example, when paginating a list
+    of 5 objects with 2 objects per page, the second page's ``start_index()``
+    would return ``3``.
 
-``end_index()`` -- Returns the 1-based index of the last object on the page,
-relative to all of the objects in the paginator's list. For example, when
-paginating a list of 5 objects with 2 objects per page, the second page's
-``end_index()`` would return ``4``.
+``end_index()``
+    Returns the 1-based index of the last object on the page, relative to all
+    of the objects in the paginator's list. For example, when paginating a list
+    of 5 objects with 2 objects per page, the second page's ``end_index()``
+    would return ``4``.
 
 Attributes
 ----------
 
-``object_list`` -- The list of objects on this page.
+``object_list``
+    The list of objects on this page.
 
-``number`` -- The 1-based page number for this page.
+``number``
+    The 1-based page number for this page.
 
-``paginator`` -- The associated ``Paginator`` object.
+``paginator``
+    The associated ``Paginator`` object.