django · nessita · Aug 28, 2025 · Aug 27, 2025 · Jun 27, 2025 · Aug 28, 2025
diff --git a/docs/contents.txt b/docs/contents.txt
@@ -25,4 +25,4 @@ Indices, glossary and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :doc:`glossary`
+* :doc:`/glossary`
diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt
@@ -29,8 +29,8 @@ You should also consider how you will handle :doc:`static files
 :doc:`error reporting</howto/error-reporting>`.
 
 Finally, before you deploy your application to production, you should run
-through our :doc:`deployment checklist<checklist>` to ensure that your
-configurations are suitable.
+through our :doc:`deployment checklist </howto/deployment/checklist>` to ensure
+that your configurations are suitable.
 
 .. _WSGI: https://wsgi.readthedocs.io/en/latest/
 .. _ASGI: https://asgi.readthedocs.io/en/latest/

diff --git a/docs/index.txt b/docs/index.txt
diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt
@@ -55,7 +55,7 @@ particular:
   as they are filed.
 
 To understand the lifecycle of your ticket once you have created it, refer to
-:doc:`triaging-tickets`.
+:ref:`triage-workflow`.
 
 Reporting user interface bugs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt
@@ -4,8 +4,8 @@ Committing code
 
 This section is addressed to the mergers and to anyone interested in knowing
 how code gets committed into Django. If you're a community member who wants to
-contribute code to Django, look at :doc:`writing-code/working-with-git`
-instead.
+contribute code to Django, look at
+:doc:`/internals/contributing/writing-code/working-with-git` instead.
 
 .. _handling-pull-requests:
 

diff --git a/docs/internals/contributing/localizing.txt b/docs/internals/contributing/localizing.txt
@@ -61,8 +61,8 @@ the date, time and numbers formatting particularities of your locale. See
 The format files aren't managed by the use of Transifex. To change them, you
 must:
 
-* :doc:`Create a pull request<writing-code/submitting-patches>` against the
-  Django Git ``main`` branch, as for any code change.
+* :ref:`Create a pull request <patch-review-checklist>` against the Django Git
+  ``main`` branch, as for any code change.
 
 * Open a ticket in Django's ticket system, set its ``Component`` field to
   ``Translations``, set the "has patch" flag, and include the link to the pull

diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt
@@ -47,14 +47,15 @@ Keep old patches up-to-date
 Oftentimes the codebase will change between a patch being submitted and the
 time it gets reviewed. Make sure it still applies cleanly and functions as
 expected. Updating a patch is both useful and important! See more on
-:doc:`writing-code/submitting-patches`.
+:ref:`patch-review-checklist`.
 
 Write some documentation
 ------------------------
 
 Django's documentation is great but it can always be improved. Did you find a
 typo? Do you think that something should be clarified? Go ahead and suggest a
-documentation patch! See also the guide on :doc:`writing-documentation`.
+documentation patch! See also the guide on
+:doc:`/internals/contributing/writing-documentation`.
 
 .. note::
 

diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt
@@ -29,11 +29,13 @@ confusion or disagreement.
 Django is a community project, and every contribution helps. We can't do this
 without **you**!
 
+.. _triage-workflow:
+
 Triage workflow
 ===============
 
 Unfortunately, not all reports in the ticket tracker provide all the
-:doc:`required details<bugs-and-features>`. A number of tickets have proposed
+:ref:`required details <reporting-bugs>`. A number of tickets have proposed
 solutions, but those don't necessarily meet all the requirements :ref:`adhering
 to the guidelines for contributing <patch-style>`.
 
@@ -168,8 +170,8 @@ Has patch
 ---------
 
 This means the ticket has an associated solution. These will be reviewed to
-ensure they adhere to the :doc:`documented guidelines
-<writing-code/submitting-patches>`.
+ensure they adhere to the :ref:`documented guidelines
+<patch-review-checklist>`.
 
 The following three fields (Needs documentation, Needs tests,
 Patch needs improvement) apply only if a patch has been supplied.
@@ -385,7 +387,7 @@ Then, you can help out by:
     several that are useful for triaging tickets and reviewing proposals as
     suggested above.
 
-    You can also find more :doc:`new-contributors`.
+    You can also find more :doc:`/internals/contributing/new-contributors`.
 
     .. _Reports page: https://code.djangoproject.com/wiki/Reports
 

diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt
@@ -504,6 +504,6 @@ JavaScript style
 ================
 
 For details about the JavaScript code style used by Django, see
-:doc:`javascript`.
+:doc:`/internals/contributing/writing-code/javascript`.
 
 .. _editorconfig: https://editorconfig.org/
diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt
@@ -15,7 +15,8 @@ If you are fixing a really trivial issue, for example changing a word in the
 documentation, the preferred way to provide the patch is using GitHub pull
 requests without a Trac ticket.
 
-See the :doc:`working-with-git` for more details on how to use pull requests.
+See the :doc:`/internals/contributing/writing-code/working-with-git` for more
+details on how to use pull requests.
 
 "Claiming" tickets
 ==================
@@ -109,19 +110,20 @@ requirements:
 
 * The code required to fix a problem or add a feature is an essential part
   of a solution, but it is not the only part. A good fix should also include a
-  :doc:`regression test <unit-tests>` to validate the behavior that has been
-  fixed and to prevent the problem from arising again. Also, if some tickets
-  are relevant to the code that you've written, mention the ticket numbers in
-  some comments in the test so that one can easily trace back the relevant
-  discussions after your patch gets committed, and the tickets get closed.
+  :doc:`regression test </internals/contributing/writing-code/unit-tests>` to
+  validate the behavior that has been fixed and to prevent the problem from
+  arising again. Also, if some tickets are relevant to the code that you've
+  written, mention the ticket numbers in some comments in the test so that one
+  can easily trace back the relevant discussions after your patch gets
+  committed, and the tickets get closed.
 
 * If the code adds a new feature, or modifies the behavior of an existing
   feature, the change should also contain documentation.
 
 When you think your work is ready to be reviewed, send :doc:`a GitHub pull
-request <working-with-git>`.
-If you can't send a pull request for some reason, you can also use patches in
-Trac. When using this style, follow these guidelines.
+request </internals/contributing/writing-code/working-with-git>`. If you can't
+send a pull request for some reason, you can also use patches in Trac. When
+using this style, follow these guidelines.
 
 * Submit patches in the format returned by the ``git diff`` command.
 

diff --git a/docs/internals/contributing/writing-code/working-with-git.txt b/docs/internals/contributing/writing-code/working-with-git.txt
@@ -4,7 +4,7 @@ Working with Git and GitHub
 
 This section explains how the community can contribute code to Django via pull
 requests. If you're interested in how :ref:`mergers <mergers-team>` handle
-them, see :doc:`../committing-code`.
+them, see :ref:`handling-pull-requests`.
 
 Below, we are going to show how to create a GitHub pull request containing the
 changes for Trac ticket #xxxxx. By creating a fully-ready pull request, you
@@ -142,7 +142,7 @@ When you think your work is ready to be pulled into Django, you should create
 a pull request at GitHub. A good pull request means:
 
 * commits with one logical change in each, following the
-  :doc:`coding style <coding-style>`,
+  :doc:`coding style </internals/contributing/writing-code/coding-style>`,
 
 * well-formed messages for each commit: a summary line and then paragraphs
   wrapped at 72 characters thereafter -- see the :ref:`committing guidelines

diff --git a/docs/internals/release-process.txt b/docs/internals/release-process.txt
@@ -31,7 +31,8 @@ own branch, called ``stable/A.B.x``, and bugfix/security releases will be
 issued from those branches.
 
 For more information about how the Django project issues new releases for
-security purposes, please see :doc:`our security policies <security>`.
+security purposes, please see :doc:`our security policies
+</internals/security>`.
 
 .. glossary::
 

diff --git a/docs/lint.py b/docs/lint.py
@@ -14,7 +14,7 @@
 from sphinxlint.checkers import checker as sphinxlint_checker
 from sphinxlint.rst import SIMPLENAME
 from sphinxlint.sphinxlint import check_text
-from sphinxlint.utils import PER_FILE_CACHES, hide_non_rst_blocks
+from sphinxlint.utils import PER_FILE_CACHES, hide_non_rst_blocks, paragraphs
 
 
 def django_check_file(filename, checkers, options=None):
@@ -136,6 +136,22 @@ def check_python_domain_in_roles(file, lines, options=None):
             yield lno, f":py domain is the default and can be omitted {role.group(0)!r}"
 
 
+_DOC_CAPTURE_TARGET_RE = re.compile(r":doc:`(?:[^<`]+<)?([^>`]+)>?`")
+
+
+@sphinxlint_checker(".rst", rst_only=True)
+def check_absolute_targets_doc_role(file, lines, options=None):
+    for paragraph_lno, paragraph in paragraphs(lines):
+        for error in _DOC_CAPTURE_TARGET_RE.finditer(paragraph):
+            target = error.group(1)
+            # Skip absolute or intersphinx refs like "python:using/windows".
+            if target.startswith("/") or ":" in target.split("/", 1)[0]:
+                continue
+            # Relative target, report as a violation.
+            error_offset = paragraph[: error.start()].count("\n")
+            yield (paragraph_lno + error_offset, target)
+
+
 import sphinxlint  # noqa: E402
 
 sphinxlint.check_file = django_check_file

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
@@ -1436,7 +1436,7 @@ default templates used by the :class:`ModelAdmin` views:
     The ``delete_queryset()`` method is given the ``HttpRequest`` and a
     ``QuerySet`` of objects to be deleted. Override this method to customize
     the deletion process for the "delete selected objects" :doc:`action
-    <actions>`.
+    </ref/contrib/admin/actions>`.
 
 .. method:: ModelAdmin.save_formset(request, form, formset, change)
 
@@ -2055,7 +2055,7 @@ default templates used by the :class:`ModelAdmin` views:
 .. method:: ModelAdmin.get_deleted_objects(objs, request)
 
     A hook for customizing the deletion process of the :meth:`delete_view` and
-    the "delete selected" :doc:`action <actions>`.
+    the "delete selected" :doc:`action </ref/contrib/admin/actions>`.
 
     The ``objs`` argument is a homogeneous iterable of objects (a ``QuerySet``
     or a list of model instances) to be deleted, and ``request`` is the

diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt
@@ -156,7 +156,7 @@ Geometry Lookups
 ----------------
 
 Geographic queries with geometries take the following general form (assuming
-the ``Zipcode`` model used in the :doc:`model-api`):
+the ``Zipcode`` model used in the :doc:`/ref/contrib/gis/model-api`):
 
 .. code-block:: text
 
@@ -192,7 +192,8 @@ used to pass a band index. On the right hand side, a tuple of the raster and
 band index can be specified.
 
 This results in the following general form for lookups involving rasters
-(assuming the ``Elevation`` model used in the :doc:`model-api`):
+(assuming the ``Elevation`` model used in the
+:doc:`/ref/contrib/gis/model-api`):
 
 .. code-block:: text
 
@@ -234,11 +235,10 @@ Distance Queries
 Introduction
 ------------
 
-Distance calculations with spatial data is tricky because, unfortunately,
-the Earth is not flat. Some distance queries with fields in a geographic
-coordinate system may have to be expressed differently because of
-limitations in PostGIS. Please see the :ref:`selecting-an-srid` section
-in the :doc:`model-api` documentation for more details.
+Distance calculations with spatial data is tricky because, unfortunately, the
+Earth is not flat. Some distance queries with fields in a geographic coordinate
+system may have to be expressed differently because of limitations in PostGIS.
+Please see the :ref:`selecting-an-srid` section for more details.
 
 .. _distance-lookups-intro:
 

diff --git a/docs/ref/contrib/gis/functions.txt b/docs/ref/contrib/gis/functions.txt
@@ -85,7 +85,8 @@ queryset is calculated:
     express the value in the units of your choice. For example,
     ``city.distance.mi`` is the distance value in miles and
     ``city.distance.km`` is the distance value in kilometers. See
-    :doc:`measure` for usage details and the list of :ref:`supported_units`.
+    :doc:`/ref/contrib/gis/measure` for usage details and the list of
+    :ref:`supported_units`.
 
 ``GeometryDistance``
 --------------------

diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt
@@ -5,6 +5,11 @@ GDAL API
 .. module:: django.contrib.gis.gdal
     :synopsis: GeoDjango's high-level interface to the GDAL library.
 
+.. _gdal-overview:
+
+Overview
+========
+
 `GDAL`__ stands for **Geospatial Data Abstraction Library**,
 and is a veritable "Swiss army knife" of GIS data functionality. A subset
 of GDAL is the `OGR`__ Simple Features Library, which specializes
@@ -24,9 +29,6 @@ to raster (image) data.
 __ https://gdal.org/
 __ https://gdal.org/user/vector_data_model.html
 
-Overview
-========
-
 .. _gdal_sample_data:
 
 Sample Data
@@ -43,6 +45,8 @@ data sets that you can use for testing. You can download them here:
     $ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/cities/cities.{shp,prj,shx,dbf}
     $ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/rasters/raster.tif
 
+.. _gdal_vector_data:
+
 Vector Data Source Objects
 ==========================
 

diff --git a/docs/ref/contrib/gis/geoip2.txt b/docs/ref/contrib/gis/geoip2.txt
@@ -5,6 +5,11 @@ Geolocation with GeoIP2
 .. module:: django.contrib.gis.geoip2
     :synopsis: Python interface for MaxMind's GeoIP2 databases.
 
+.. _geoip2-overview:
+
+Overview
+========
+
 The :class:`GeoIP2` object is a wrapper for the :pypi:`MaxMind geoip2 Python
 library <geoip2>`. [#]_
 

diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt
@@ -5,6 +5,8 @@ GEOS API
 .. module:: django.contrib.gis.geos
     :synopsis: GeoDjango's high-level interface to the GEOS library.
 
+.. _geos-overview:
+
 Background
 ==========
 

diff --git a/docs/ref/contrib/gis/install/geolibs.txt b/docs/ref/contrib/gis/install/geolibs.txt
@@ -2,19 +2,24 @@
 Installing Geospatial libraries
 ===============================
 
+.. _geolibs-list:
+
+Geospatial libraries
+====================
+
 GeoDjango uses and/or provides interfaces for the following open source
 geospatial libraries:
 
-========================  ====================================  ================================  =======================================================
-Program                   Description                           Required                          Supported Versions
-========================  ====================================  ================================  =======================================================
-:doc:`GEOS <../geos>`     Geometry Engine Open Source           Yes                               3.14, 3.13, 3.12, 3.11, 3.10, 3.9, 3.8
-`PROJ`_                   Cartographic Projections library      Yes (PostgreSQL and SQLite only)  9.x, 8.x, 7.x, 6.x
-:doc:`GDAL <../gdal>`     Geospatial Data Abstraction Library   Yes                               3.11, 3.10, 3.9, 3.8, 3.7, 3.6, 3.5, 3.4, 3.3, 3.2, 3.1
-:doc:`GeoIP <../geoip2>`  IP-based geolocation library          No                                2
-`PostGIS`__               Spatial extensions for PostgreSQL     Yes (PostgreSQL only)             3.5, 3.4, 3.3, 3.2, 3.1
-`SpatiaLite`__            Spatial extensions for SQLite         Yes (SQLite only)                 5.1, 5.0, 4.3
-========================  ====================================  ================================  =======================================================
+==============================  ====================================  ================================  =======================================================
+Program                         Description                           Required                          Supported Versions
+==============================  ====================================  ================================  =======================================================
+:ref:`GEOS <geos-overview>`     Geometry Engine Open Source           Yes                               3.14, 3.13, 3.12, 3.11, 3.10, 3.9, 3.8
+`PROJ`_                         Cartographic Projections library      Yes (PostgreSQL and SQLite only)  9.x, 8.x, 7.x, 6.x
+:ref:`GDAL <gdal-overview>`     Geospatial Data Abstraction Library   Yes                               3.11, 3.10, 3.9, 3.8, 3.7, 3.6, 3.5, 3.4, 3.3, 3.2, 3.1
+:ref:`GeoIP <geoip2-overview>`  IP-based geolocation library          No                                2
+`PostGIS`__                     Spatial extensions for PostgreSQL     Yes (PostgreSQL only)             3.5, 3.4, 3.3, 3.2, 3.1
+`SpatiaLite`__                  Spatial extensions for SQLite         Yes (SQLite only)                 5.1, 5.0, 4.3
+==============================  ====================================  ================================  =======================================================
 
 Note that older or more recent versions of these libraries *may* also work
 totally fine with GeoDjango. Your mileage may vary.
@@ -235,7 +240,7 @@ GDAL
 
 `GDAL`__ is an excellent open source geospatial library that has support for
 reading most vector and raster spatial data formats. Currently, GeoDjango only
-supports :doc:`GDAL's vector data <../gdal>` capabilities [#]_.
+supports :ref:`GDAL's vector data <gdal_vector_data>` capabilities [#]_.
 :ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL.
 
 First download the latest GDAL release version and untar the archive:

diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt
@@ -8,7 +8,7 @@ In general, GeoDjango installation requires:
 
 #. :ref:`Python and Django <django>`
 #. :ref:`spatial_database`
-#. :doc:`geolibs`
+#. :ref:`geolibs-list`
 
 Details for each of the requirements and installation instructions
 are provided in the sections below. In addition, platform-specific