Fixed #25205 -- Removed doc references to deprecated GeoManager class.

7 files changed, 41 insertions, 48 deletions

diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt
index cecb02de6c..36e8e2a9bf 100644
--- a/docs/ref/contrib/gis/db-api.txt
+++ b/docs/ref/contrib/gis/db-api.txt
@@ -226,18 +226,17 @@ in southern Texas::
         # A projected coordinate system (only valid for South Texas!)
         # is used, units are in meters.
         point = models.PointField(srid=32140)
-        objects = models.GeoManager()
 
 Then distance queries may be performed as follows::
 
-    >>> from django.contrib.gis.geos import *
+    >>> from django.contrib.gis.geos import fromstr
     >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance``
-    >>> from geoapp import SouthTexasCity
+    >>> from geoapp.models import SouthTexasCity
     # Distances will be calculated from this point, which does not have to be projected.
     >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326)
     # If numeric parameter, units of field (meters in this case) are assumed.
     >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000))
-    # Find all Cities within 7 km, > 20 miles away, and > 100 chains  away (an obscure unit)
+    # Find all Cities within 7 km, > 20 miles away, and > 100 chains away (an obscure unit)
     >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7)))
     >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20)))
     >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100)))
diff --git a/docs/ref/contrib/gis/functions.txt b/docs/ref/contrib/gis/functions.txt
index 6f59010d5b..06fe57fe99 100644
--- a/docs/ref/contrib/gis/functions.txt
+++ b/docs/ref/contrib/gis/functions.txt
@@ -216,8 +216,9 @@ In the following example, the distance from the city of Hobart to every other
 :class:`~django.contrib.gis.db.models.PointField` in the ``AustraliaCity``
 queryset is calculated::
 
+    >>> from django.contrib.gis.db.models.functions import Distance
     >>> pnt = AustraliaCity.objects.get(name='Hobart').point
-    >>> for city in AustraliaCity.objects.distance('point', pnt):
+    >>> for city in AustraliaCity.objects.annotate(distance=Distance('point', pnt)):
     ...     print(city.name, city.distance)
     Wollongong 990071.220408 m
     Shellharbour 972804.613941 m
diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt
index 8dc4c7dac7..d4b83e86c8 100644
--- a/docs/ref/contrib/gis/geoquerysets.txt
+++ b/docs/ref/contrib/gis/geoquerysets.txt
@@ -629,6 +629,8 @@ Oracle      ``SDO_WITHIN_DISTANCE(poly, geom, 5)``
 
     This lookup is not available on SpatiaLite.
 
+.. _geoqueryset-methods:
+
 ``GeoQuerySet`` Methods
 =======================
 
diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt
index 69589b05c3..9c7bb82ffb 100644
--- a/docs/ref/contrib/gis/layermapping.txt
+++ b/docs/ref/contrib/gis/layermapping.txt
@@ -57,7 +57,6 @@ Example
     class TestGeo(models.Model):
         name = models.CharField(max_length=25) # corresponds to the 'str' field
         poly = models.PolygonField(srid=4269) # we want our model in a different SRID
-        objects = models.GeoManager()
 
         def __str__(self):              # __unicode__ on Python 2
             return 'Name: %s' % self.name
diff --git a/docs/ref/contrib/gis/model-api.txt b/docs/ref/contrib/gis/model-api.txt
index d6fde26c14..fb44a5c41c 100644
--- a/docs/ref/contrib/gis/model-api.txt
+++ b/docs/ref/contrib/gis/model-api.txt
@@ -14,7 +14,6 @@ of a `Digital Elevation Model`__ as our examples::
     class Zipcode(models.Model):
         code = models.CharField(max_length=5)
         poly = models.PolygonField()
-        objects = models.GeoManager()
 
     class Elevation(models.Model):
         name = models.CharField(max_length=100)
@@ -246,36 +245,40 @@ determining `when to use geography data type over geometry data type
 .. currentmodule:: django.contrib.gis.db.models
 .. class:: GeoManager
 
-In order to conduct geographic queries, each geographic model requires
-a ``GeoManager`` model manager.  This manager allows for the proper SQL
-construction for geographic queries; thus, without it, all geographic filters
-will fail.
+The ``GeoManager`` is required in order to use the legacy
+:ref:`geoqueryset-methods`.
 
-.. note::
+.. deprecated:: 1.9
 
-    Geographic filtering support is limited to geometry fields. ``RasterField``
-    does not currently allow spatial querying.
+    All ``GeoQuerySet`` methods have been deprecated and replaced by
+    :doc:`equivalent database functions </ref/contrib/gis/functions>`. As soon
+    as the legacy methods have been replaced in your code, you should be able
+    to remove the special ``GeoManager`` from your GIS-enabled classes.
 
-It should also be noted that ``GeoManager`` is required even if the
-model does not have a geographic field itself, e.g., in the case of a
-``ForeignKey`` relation to a model with a geographic field.  For example,
-if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode``
-model::
+.. versionchanged:: 1.9
 
-    from django.contrib.gis.db import models
+    In older versions, the manager was required to conduct geographic queries.
+    Without it, all geographic filters failed.
+
+    ``GeoManager`` was required even if the model did not have a geographic
+    field itself, e.g., in the case of a ``ForeignKey`` relation to a model
+    with a geographic field.  For example, if we had an ``Address`` model with
+    a ``ForeignKey`` to our ``Zipcode`` model::
+
+        from django.contrib.gis.db import models
 
-    class Address(models.Model):
-        num = models.IntegerField()
-        street = models.CharField(max_length=100)
-        city = models.CharField(max_length=100)
-        state = models.CharField(max_length=2)
-        zipcode = models.ForeignKey(Zipcode, on_delete=models.CASCADE)
-        objects = models.GeoManager()
+        class Address(models.Model):
+            num = models.IntegerField()
+            street = models.CharField(max_length=100)
+            city = models.CharField(max_length=100)
+            state = models.CharField(max_length=2)
+            zipcode = models.ForeignKey(Zipcode, on_delete=models.CASCADE)
+            objects = models.GeoManager()
 
-The geographic manager is needed to do spatial queries on related ``Zipcode`` objects,
-for example::
+    The geographic manager was needed to do spatial queries on related
+    ``Zipcode`` objects, for example::
 
-    qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')
+        qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')
 
 .. rubric:: Footnotes
 .. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengeospatial.org/standards/sfs>`_.
diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt
index f869e97729..a41b5ed042 100644
--- a/docs/ref/contrib/gis/tutorial.txt
+++ b/docs/ref/contrib/gis/tutorial.txt
@@ -238,20 +238,14 @@ model to represent this data::
         lon = models.FloatField()
         lat = models.FloatField()
 
-        # GeoDjango-specific: a geometry field (MultiPolygonField), and
-        # overriding the default manager with a GeoManager instance.
+        # GeoDjango-specific: a geometry field (MultiPolygonField)
         mpoly = models.MultiPolygonField()
-        objects = models.GeoManager()
 
         # Returns the string representation of the model.
         def __str__(self):              # __unicode__ on Python 2
             return self.name
 
-Please note two important things:
-
-1. The ``models`` module is imported from ``django.contrib.gis.db``.
-2. You must override the model's default manager with
-   :class:`~django.contrib.gis.db.models.GeoManager` to perform spatial queries.
+Note that the ``models`` module is imported from ``django.contrib.gis.db``.
 
 The default spatial reference system for geometry fields is WGS84 (meaning
 the `SRID`__ is 4326) -- in other words, the field coordinates are in
@@ -579,7 +573,6 @@ directly into the ``models.py`` of a GeoDjango application::
         lon = models.FloatField()
         lat = models.FloatField()
         geom = models.MultiPolygonField(srid=4326)
-        objects = models.GeoManager()
 
     # Auto-generated `LayerMapping` dictionary for WorldBorder model
     worldborders_mapping = {
diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt
index bd46a34c07..ae5bed536f 100644
--- a/docs/topics/db/managers.txt
+++ b/docs/topics/db/managers.txt
@@ -455,13 +455,10 @@ Throughout this section, we will use the term "automatic manager" to mean a
 manager that Django creates for you -- either as a default manager on a model
 with no managers, or to use temporarily when accessing related objects.
 
-Sometimes this default class won't be the right choice. One example is in the
-:mod:`django.contrib.gis` application that ships with Django itself. All ``gis``
-models must use a special manager class (:class:`~django.contrib.gis.db.models.GeoManager`)
-because they need a special queryset (:class:`~django.contrib.gis.db.models.GeoQuerySet`)
-to be used for interacting with the database.  It turns out that models which require
-a special manager like this need to use the same manager class wherever an automatic
-manager is created.
+Sometimes this default class won't be the right choice. The default manager
+may not have all the methods you need to work with your data. A custom manager
+class of your own will allow you to create custom ``QuerySet`` objects to give
+you the information you need.
 
 Django provides a way for custom manager developers to say that their manager
 class should be used for automatic managers whenever it is the default manager
@@ -490,8 +487,7 @@ it will use :class:`django.db.models.Manager`.
 Writing correct Managers for use in automatic Manager instances
 ---------------------------------------------------------------
 
-As already suggested by the :mod:`django.contrib.gis` example, above, the
-``use_for_related_fields`` feature is primarily for managers that need to
+The ``use_for_related_fields`` feature is primarily for managers that need to
 return a custom ``QuerySet`` subclass. In providing this functionality in your
 manager, there are a couple of things to remember.