Fixed #27674 -- Deprecated GeoModelAdmin and OSMGeoAdmin.

Co-authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>

4 files changed, 54 insertions, 20 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 09be9e66e4..23af7315dd 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -54,6 +54,9 @@ details on these changes.
   * ``django.db.models.functions.TruncQuarter()``
   * ``django.db.models.functions.TruncYear()``
 
+* The ``django.contrib.gis.admin.GeoModelAdmin`` and ``OSMGeoAdmin`` classes
+  will be removed.
+
 .. _deprecation-removed-in-4.1:
 
 4.1
diff --git a/docs/ref/contrib/gis/admin.txt b/docs/ref/contrib/gis/admin.txt
index 6d7e8b77df..ee66e3f2c1 100644
--- a/docs/ref/contrib/gis/admin.txt
+++ b/docs/ref/contrib/gis/admin.txt
@@ -5,6 +5,24 @@ GeoDjango's admin site
 .. module:: django.contrib.gis.admin
     :synopsis: GeoDjango's extensions to the admin site.
 
+``GISModelAdmin``
+=================
+
+.. versionadded:: 4.0
+
+.. class:: GISModelAdmin
+
+    .. attribute:: gis_widget
+
+        The widget class to be used for
+        :class:`~django.contrib.gis.db.models.GeometryField`. Defaults to
+        :class:`~django.contrib.gis.forms.widgets.OSMWidget`.
+
+    .. attribute:: gis_widget_kwargs
+
+        The keyword arguments that would be passed to the :attr:`gis_widget`.
+        Defaults to an empty dictionary.
+
 ``GeoModelAdmin``
 =================
 
@@ -57,6 +75,11 @@ GeoDjango's admin site
         ``modifiable=False``, actually displays the geometry in a map,
         but disables the ability to edit its vertices.
 
+    .. deprecated:: 4.0
+
+        This class is deprecated. Use :class:`~django.contrib.admin.ModelAdmin`
+        instead.
+
 ``OSMGeoAdmin``
 ===============
 
@@ -64,5 +87,7 @@ GeoDjango's admin site
 
     A subclass of :class:`GeoModelAdmin` that uses a Spherical Mercator projection
     with `OpenStreetMap <https://www.openstreetmap.org/>`_ street data tiles.
-    See the :ref:`OSMGeoAdmin introduction <osmgeoadmin-intro>`
-    in the tutorial for a usage example.
+
+    .. deprecated:: 4.0
+
+        This class is deprecated. Use :class:`GISModelAdmin` instead.
diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt
index 0bdd09e163..1b8f54495a 100644
--- a/docs/ref/contrib/gis/tutorial.txt
+++ b/docs/ref/contrib/gis/tutorial.txt
@@ -697,26 +697,26 @@ Putting your data on the map
 Geographic Admin
 ----------------
 
-GeoDjango extends :doc:`Django's admin application </ref/contrib/admin/index>`
-with support for editing geometry fields.
+:doc:`Django's admin application </ref/contrib/admin/index>` supports editing
+geometry fields.
 
 Basics
 ~~~~~~
 
-GeoDjango also supplements the Django admin by allowing users to create
-and modify geometries on a JavaScript slippy map (powered by `OpenLayers`_).
+The Django admin allows users to create and modify geometries on a JavaScript
+slippy map (powered by `OpenLayers`_).
 
-Let's dive right in.  Create a file called ``admin.py`` inside the
-``world`` application with the following code::
+Let's dive right in. Create a file called ``admin.py`` inside the ``world``
+application with the following code::
 
     from django.contrib.gis import admin
     from .models import WorldBorder
 
-    admin.site.register(WorldBorder, admin.GeoModelAdmin)
+    admin.site.register(WorldBorder, admin.ModelAdmin)
 
 Next, edit your ``urls.py`` in the ``geodjango`` application folder as follows::
 
-    from django.contrib.gis import admin
+    from django.contrib import admin
     from django.urls import include, path
 
     urlpatterns = [
@@ -745,24 +745,22 @@ position.
 .. _Vector Map Level 0: http://web.archive.org/web/20201024202709/https://earth-info.nga.mil/publications/vmap0.html
 .. _OSGeo: https://www.osgeo.org/
 
-.. _osmgeoadmin-intro:
-
-``OSMGeoAdmin``
-~~~~~~~~~~~~~~~
+``GISModelAdmin``
+~~~~~~~~~~~~~~~~~
 
-With the :class:`~django.contrib.gis.admin.OSMGeoAdmin`, GeoDjango uses
-an `OpenStreetMap`_ layer in the admin.
+With the :class:`~django.contrib.gis.admin.GISModelAdmin`, GeoDjango uses an
+`OpenStreetMap`_ layer in the admin.
 This provides more context (including street and thoroughfare details) than
-available with the :class:`~django.contrib.gis.admin.GeoModelAdmin`
-(which uses the `Vector Map Level 0`_ WMS dataset hosted at `OSGeo`_).
+available with the :class:`~django.contrib.admin.ModelAdmin` (which uses the
+`Vector Map Level 0`_ WMS dataset hosted at `OSGeo`_).
 
 The PROJ datum shifting files must be installed (see the :ref:`PROJ
 installation instructions <proj4>` for more details).
 
-If you meet this requirement, then substitute the ``OSMGeoAdmin`` option class
+If you meet this requirement, then use the ``GISModelAdmin`` option class
 in your ``admin.py`` file::
 
-    admin.site.register(WorldBorder, admin.OSMGeoAdmin)
+    admin.site.register(WorldBorder, admin.GISModelAdmin)
 
 .. rubric:: Footnotes
 
diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt
index af168a6d33..6ec04824f2 100644
--- a/docs/releases/4.0.txt
+++ b/docs/releases/4.0.txt
@@ -171,6 +171,10 @@ Minor features
 * :class:`~django.contrib.gis.gdal.GDALRaster` now allows creating rasters in
   any GDAL virtual filesystem.
 
+* The new :class:`~django.contrib.gis.admin.GISModelAdmin` class allows
+  customizing the widget used for ``GeometryField``. This is encouraged instead
+  of deprecated ``GeoModelAdmin`` and ``OSMGeoAdmin``.
+
 :mod:`django.contrib.messages`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -718,6 +722,10 @@ Miscellaneous
   respectively in Django 5.0. If you need the previous behavior, explicitly set
   ``default`` to ``Value([])``, ``Value('[]')``, or ``Value('')``.
 
+* The ``django.contrib.gis.admin.GeoModelAdmin`` and ``OSMGeoAdmin`` classes
+  are deprecated. Use :class:`~django.contrib.admin.ModelAdmin` and
+  :class:`~django.contrib.gis.admin.GISModelAdmin` instead.
+
 Features removed in 4.0
 =======================