Fixed #14758 - Remove entire method signatures from QuerySet headings - thanks adamv for the patch.

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

docs/ref/models/querysets.txt

@@ -119,22 +119,23 @@ described here.
 QuerySet API
 ============
 
-Though you usually won't create one manually -- you'll go through a :class:`Manager` -- here's the formal declaration of a ``QuerySet``:
+Though you usually won't create one manually -- you'll go through a
+:class:`Manager` -- here's the formal declaration of a ``QuerySet``:
 
 .. class:: QuerySet([model=None])
 
 Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining
 filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets.
 
-QuerySet methods that return new QuerySets
+Methods that return new QuerySets
-------------------------------------------
+---------------------------------
 
 Django provides a range of ``QuerySet`` refinement methods that modify either
 the types of results returned by the ``QuerySet`` or the way its SQL query is
 executed.
 
-``filter(**kwargs)``
+filter
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~
 
 .. method:: filter(**kwargs)
 
@@ -145,8 +146,8 @@ The lookup parameters (``**kwargs``) should be in the format described in
 `Field lookups`_ below. Multiple parameters are joined via ``AND`` in the
 underlying SQL statement.
 
-``exclude(**kwargs)``
+exclude
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~
 
 .. method:: exclude(**kwargs)
 
@@ -180,8 +181,8 @@ In SQL terms, that evaluates to::
 
 Note the second example is more restrictive.
 
-``annotate(*args, **kwargs)``
+annotate
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~
 
 .. method:: annotate(*args, **kwargs)
 
@@ -224,8 +225,8 @@ control the name of the annotation::
 For an in-depth discussion of aggregation, see :doc:`the topic guide on
 Aggregation </topics/db/aggregation>`.
 
-``order_by(*fields)``
+order_by
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~
 
 .. method:: order_by(*fields)
 
@@ -267,8 +268,8 @@ primary key if there is no ``Meta.ordering`` specified. For example::
 ...since the ``Blog`` model has no default ordering specified.
 
 Be cautious when ordering by fields in related models if you are also using
-``distinct()``. See the note in the `distinct()`_ section for an explanation
+``distinct()``. See the note in :meth:`distinct` for an explanation of how
-of how related model ordering can change the expected results.
+related model ordering can change the expected results.
 
 It is permissible to specify a multi-valued field to order the results by (for
 example, a ``ManyToMany`` field). Normally this won't be a sensible thing to
@@ -280,11 +281,6 @@ fields with care and make sure the results are what you expect.
 
 .. versionadded:: 1.0
 
-If you don't want any ordering to be applied to a query, not even the default
-ordering, call ``order_by()`` with no parameters.
-
-.. versionadded:: 1.0
-
 The syntax for ordering across related models has changed. See the `Django 0.96
 documentation`_ for the old behaviour.
 
@@ -294,14 +290,17 @@ There's no way to specify whether ordering should be case sensitive. With
 respect to case-sensitivity, Django will order results however your database
 backend normally orders them.
 
+If you don't want any ordering to be applied to a query, not even the default
+ordering, call ``order_by()`` with no parameters.
+
 .. versionadded:: 1.1
 
 You can tell if a query is ordered or not by checking the
 :attr:`QuerySet.ordered` attribute, which will be ``True`` if the
 ``QuerySet`` has been ordered in any way.
 
-``reverse()``
+reverse
-~~~~~~~~~~~~~
+~~~~~~~
 
 .. method:: reverse()
 
@@ -330,8 +329,8 @@ a model which defines a default ordering, or when using
 ordering was undefined prior to calling ``reverse()``, and will remain
 undefined afterward).
 
-``distinct()``
+distinct
-~~~~~~~~~~~~~~
+~~~~~~~~
 
 .. method:: distinct()
 
@@ -345,7 +344,7 @@ query spans multiple tables, it's possible to get duplicate results when a
 ``QuerySet`` is evaluated. That's when you'd use ``distinct()``.
 
 .. note::
-    Any fields used in an `order_by(*fields)`_ call are included in the SQL
+    Any fields used in an :meth:`order_by` call are included in the SQL
     ``SELECT`` columns. This can sometimes lead to unexpected results when
     used in conjunction with ``distinct()``. If you order by fields from a
     related model, those fields will be added to the selected columns and they
@@ -363,8 +362,8 @@ query spans multiple tables, it's possible to get duplicate results when a
     ``values()`` together, be careful when ordering by fields not in the
     ``values()`` call.
 
-``values(*fields)``
+values
-~~~~~~~~~~~~~~~~~~~
+~~~~~~
 
 .. method:: values(*fields)
 
@@ -419,9 +418,11 @@ A few subtleties that are worth mentioning:
 
         >>> Entry.objects.values('blog_id')
         [{'blog_id': 1}, ...]
+
     * When using ``values()`` together with ``distinct()``, be aware that
-      ordering can affect the results. See the note in the `distinct()`_
+      ordering can affect the results. See the note in :meth:`distinct` for
-      section, above, for details.
+      details.
+
     * If you use a ``values()`` clause after an ``extra()`` clause,
       any fields defined by a ``select`` argument in the ``extra()``
       must be explicitly included in the ``values()`` clause. However,
@@ -472,8 +473,8 @@ and ``ManyToManyField`` attributes::
    pronounced if you include multiple such fields in your ``values()`` query,
    in which case all possible combinations will be returned.
 
-``values_list(*fields)``
+values_list
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~
 
 .. method:: values_list(*fields)
 
@@ -502,8 +503,8 @@ It is an error to pass in ``flat`` when there is more than one field.
 If you don't pass any values to ``values_list()``, it will return all the
 fields in the model, in the order they were declared.
 
-``dates(field, kind, order='ASC')``
+dates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~
 
 .. method:: dates(field, kind, order='ASC')
 
@@ -538,8 +539,8 @@ Examples::
     >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
     [datetime.datetime(2005, 3, 20)]
 
-``none()``
+none
-~~~~~~~~~~
+~~~~
 
 .. method:: none()
 
@@ -555,14 +556,14 @@ Examples::
     >>> Entry.objects.none()
     []
 
-``all()``
+all
-~~~~~~~~~
+~~~
 
 .. method:: all()
 
 .. versionadded:: 1.0
 
-Returns a ''copy'' of the current ``QuerySet`` (or ``QuerySet`` subclass you
+Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass you
 pass in). This can be useful in some situations where you might want to pass
 in either a model manager or a ``QuerySet`` and do further filtering on the
 result. You can safely call ``all()`` on either object and then you'll
@@ -570,8 +571,8 @@ definitely have a ``QuerySet`` to work with.
 
 .. _select-related:
 
-``select_related()``
+select_related
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~
 
 .. method:: select_related()
 
@@ -691,8 +692,8 @@ related object.
 ``OneToOneFields`` will not be traversed in the reverse direction if you
 are performing a depth-based ``select_related``.
 
-``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``
+extra
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~
 
 .. method:: extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)
 
@@ -854,8 +855,8 @@ of the arguments is required, but you should use at least one of them.
 
         Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
 
-``defer(*fields)``
+defer
-~~~~~~~~~~~~~~~~~~
+~~~~~
 
 .. method:: defer(*fields)
 
@@ -882,7 +883,9 @@ deferred set::
     # Defers both the body and headline fields.
     Entry.objects.defer("body").filter(rating=5).defer("headline")
 
-The order in which fields are added to the deferred set does not matter. Calling ``defer()`` with a field name that has already been deferred is harmless (the field will still be deferred).
+The order in which fields are added to the deferred set does not matter.
+Calling ``defer()`` with a field name that has already been deferred is
+harmless (the field will still be deferred).
 
 You can defer loading of fields in related models (if the related models are
 loading via ``select_related()``) by using the standard double-underscore
@@ -914,8 +917,8 @@ eventually).
     bother using ``defer()``; leave it until your query construction has
     settled down and you understand where the hot-points are.
 
-``only(*fields)``
+only
-~~~~~~~~~~~~~~~~~
+~~~~
 
 .. method:: only(*fields)
 
@@ -952,8 +955,8 @@ logically::
     # existing set of fields).
     Entry.objects.defer("body").only("headline", "body")
 
-``using(alias)``
+using
-~~~~~~~~~~~~~~~~
+~~~~~
 
 .. method:: using(alias)
 
@@ -973,8 +976,8 @@ For example::
     >>> Entry.objects.using('backup')
 
 
-QuerySet methods that do not return QuerySets
+Methods that do not return QuerySets
----------------------------------------------
+------------------------------------
 
 The following ``QuerySet`` methods evaluate the ``QuerySet`` and return
 something *other than* a ``QuerySet``.
@@ -982,8 +985,8 @@ something *other than* a ``QuerySet``.
 These methods do not use a cache (see :ref:`caching-and-querysets`). Rather,
 they query the database each time they're called.
 
-``get(**kwargs)``
+get
-~~~~~~~~~~~~~~~~~
+~~~
 
 .. method:: get(**kwargs)
 
@@ -1011,8 +1014,8 @@ The ``DoesNotExist`` exception inherits from
     except ObjectDoesNotExist:
         print "Either the entry or blog doesn't exist."
 
-``create(**kwargs)``
+create
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~
 
 .. method:: create(**kwargs)
 
@@ -1031,12 +1034,12 @@ The :ref:`force_insert <ref-models-force-insert>` parameter is documented
 elsewhere, but all it means is that a new object will always be created.
 Normally you won't need to worry about this. However, if your model contains a
 manual primary key value that you set and if that value already exists in the
-database, a call to ``create()`` will fail with an ``IntegrityError`` since
+database, a call to ``create()`` will fail with an :exc:`IntegrityError` since
-primary keys must be unique. So remember to be prepared to handle the
+primary keys must be unique. So remember to be prepared to handle the exception
-exception if you are using manual primary keys.
+if you are using manual primary keys.
 
-``get_or_create(**kwargs)``
+get_or_create
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
 
 .. method:: get_or_create(**kwargs)
 
@@ -1105,8 +1108,8 @@ has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec.
 
 .. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
 
-``count()``
+count
-~~~~~~~~~~~
+~~~~~
 
 .. method:: count()
 
@@ -1131,8 +1134,8 @@ Depending on which database you're using (e.g. PostgreSQL vs. MySQL),
 is an underlying implementation quirk that shouldn't pose any real-world
 problems.
 
-``in_bulk(id_list)``
+in_bulk
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~
 
 .. method:: in_bulk(id_list)
 
@@ -1150,8 +1153,8 @@ Example::
 
 If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.
 
-``iterator()``
+iterator
-~~~~~~~~~~~~~~
+~~~~~~~~
 
 .. method:: iterator()
 
@@ -1168,8 +1171,8 @@ been evaluated will force it to evaluate again, repeating the query.
 
 .. _iterator: http://www.python.org/dev/peps/pep-0234/
 
-``latest(field_name=None)``
+latest
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~
 
 .. method:: latest(field_name=None)
 
@@ -1190,8 +1193,8 @@ exist with the given parameters.
 
 Note ``latest()`` exists purely for convenience and readability.
 
-``aggregate(*args, **kwargs)``
+aggregate
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~
 
 .. method:: aggregate(*args, **kwargs)
 
@@ -1224,8 +1227,8 @@ control the name of the aggregation value that is returned::
 For an in-depth discussion of aggregation, see :doc:`the topic guide on
 Aggregation </topics/db/aggregation>`.
 
-``exists()``
+exists
-~~~~~~~~~~~~
+~~~~~~
 
 .. method:: exists()
 
@@ -1240,8 +1243,8 @@ that it will be at some point, then using ``some_query_set.exists()`` will do
 more overall work (an additional query) than simply using
 ``bool(some_query_set)``.
 
-``update(**kwargs)``
+update
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~
 
 .. method:: update(**kwargs)
 
@@ -1265,8 +1268,8 @@ The ``update()`` method does a bulk update and does not call any ``save()``
 methods on your models, nor does it emit the ``pre_save`` or ``post_save``
 signals (which are a consequence of calling ``save()``).
 
-``delete()``
+delete
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~
 
 .. method:: delete()
 
@@ -1736,7 +1739,8 @@ SQL equivalent::
 
 Note this is only available in MySQL and requires direct manipulation of the
 database to add the full-text index. By default Django uses BOOLEAN MODE for
-full text searches. `Please check MySQL documentation for additional details. <http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_
+full text searches. `See the MySQL documentation for additional details.
+<http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_
 
 
 .. fieldlookup:: regex
@@ -1805,8 +1809,8 @@ Django provides the following aggregation functions in the
 aggregate functions, see
 :doc:`the topic guide on aggregation </topics/db/aggregation>`.
 
-``Avg``
+Avg
-~~~~~~~
+~~~
 
 .. class:: Avg(field)
 
@@ -1815,8 +1819,8 @@ Returns the mean value of the given field.
     * Default alias: ``<field>__avg``
     * Return type: float
 
-``Count``
+Count
-~~~~~~~~~
+~~~~~
 
 .. class:: Count(field, distinct=False)
 
@@ -1832,8 +1836,8 @@ Has one optional argument:
     If distinct=True, the count will only include unique instances. This has
     the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``.
 
-``Max``
+Max
-~~~~~~~
+~~~
 
 .. class:: Max(field)
 
@@ -1842,8 +1846,8 @@ Returns the maximum value of the given field.
     * Default alias: ``<field>__max``
     * Return type: same as input field
 
-``Min``
+Min
-~~~~~~~
+~~~
 
 .. class:: Min(field)
 
@@ -1852,8 +1856,8 @@ Returns the minimum value of the given field.
     * Default alias: ``<field>__min``
     * Return type: same as input field
 
-``StdDev``
+StdDev
-~~~~~~~~~~
+~~~~~~
 
 .. class:: StdDev(field, sample=False)
 
@@ -1875,8 +1879,8 @@ Has one optional argument:
     available as an extension module for SQLite. Consult the SQlite
     documentation for instructions on obtaining and installing this extension.
 
-``Sum``
+Sum
-~~~~~~~
+~~~
 
 .. class:: Sum(field)
 
@@ -1885,8 +1889,8 @@ Computes the sum of all values of the given field.
     * Default alias: ``<field>__sum``
     * Return type: same as input field
 
-``Variance``
+Variance
-~~~~~~~~~~~~
+~~~~~~~~
 
 .. class:: Variance(field, sample=False)