Fixed #36329 -- Removed non-code custom link text when cross-referencing Python objects.

Thanks Bruno Alla, Sarah Boyce, and Jacob Walls for reviews.

Co-authored-by: Sarah Boyce <42296566+sarahboyce@users.noreply.github.com>

6 files changed, 47 insertions, 45 deletions

diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index b542fe7d71..fa5b4b9540 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -111,6 +111,8 @@ Built-in Expressions
     ``django.db.models.aggregates``, but for convenience they're available and
     usually imported from :mod:`django.db.models`.
 
+.. _f-expressions:
+
 ``F()`` expressions
 -------------------
 
@@ -493,7 +495,7 @@ should be invoked for each distinct value of ``expressions`` (or set of
 values, for multiple ``expressions``). The argument is only supported on
 aggregates that have :attr:`~Aggregate.allow_distinct` set to ``True``.
 
-The ``filter`` argument takes a :class:`Q object <django.db.models.Q>` that's
+The ``filter`` argument takes a :ref:`Q object <q-objects>` that's
 used to filter the rows that are aggregated. See :ref:`conditional-aggregation`
 and :ref:`filtering-on-annotations` for example usage.
 
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 0b62143cc0..4e515d428e 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -561,8 +561,8 @@ The primary key field is read-only. If you change the value of the primary
 key on an existing object and then save it, a new object will be created
 alongside the old one.
 
-The primary key field is set to ``None`` when
-:meth:`deleting <django.db.models.Model.delete>` an object.
+The primary key field is set to ``None`` when calling a model instance’s
+:meth:`~django.db.models.Model.delete` method.
 
 ``unique``
 ----------
@@ -2436,9 +2436,9 @@ Field API reference
     Python types to database (:meth:`get_prep_value`) and vice-versa
     (:meth:`from_db_value`).
 
-    A field is thus a fundamental piece in different Django APIs, notably,
-    :class:`models <django.db.models.Model>` and :class:`querysets
-    <django.db.models.query.QuerySet>`.
+    A field is thus a fundamental piece in different Django APIs, notably the
+    :class:`~django.db.models.Model` and the
+    :class:`~django.db.models.query.QuerySet` APIs.
 
     In models, a field is instantiated as a class attribute and represents a
     particular table column, see :doc:`/topics/db/models`. It has attributes
@@ -2598,7 +2598,7 @@ Field API reference
 
         See :ref:`converting-model-field-to-serialization` for usage.
 
-    When using :class:`model forms <django.forms.ModelForm>`, the ``Field``
+    When using :doc:`model forms </topics/forms/modelforms>`, the ``Field``
     needs to know which form field it should be represented by:
 
     .. method:: formfield(form_class=None, choices_form_class=None, **kwargs)
diff --git a/docs/ref/models/indexes.txt b/docs/ref/models/indexes.txt
index 6f8dd39fb7..c9de422ad3 100644
--- a/docs/ref/models/indexes.txt
+++ b/docs/ref/models/indexes.txt
@@ -211,10 +211,10 @@ filtering.
 
 See the PostgreSQL documentation for more details about `covering indexes`_.
 
-.. admonition:: Restrictions on PostgreSQL
+.. admonition:: PostgreSQL-specific indexes
 
-    PostgreSQL supports covering B-Tree, :class:`GiST indexes
-    <django.contrib.postgres.indexes.GistIndex>`, and :class:`SP-GiST indexes
-    <django.contrib.postgres.indexes.SpGistIndex>`.
+    In addition to B-Tree indexes (via :class:`Index`), PostgreSQL also
+    supports :class:`~django.contrib.postgres.indexes.GistIndex` and
+    :class:`~django.contrib.postgres.indexes.SpGistIndex` indexes.
 
 .. _covering indexes: https://www.postgresql.org/docs/current/indexes-index-only-scans.html
diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
index a8be767aaf..323de16b1f 100644
--- a/docs/ref/models/instances.txt
+++ b/docs/ref/models/instances.txt
@@ -632,10 +632,9 @@ the value of 11 will be written back to the database.
 The process can be made robust, :ref:`avoiding a race condition
 <avoiding-race-conditions-using-f>`, as well as slightly faster by expressing
 the update relative to the original field value, rather than as an explicit
-assignment of a new value. Django provides :class:`F expressions
-<django.db.models.F>` for performing this kind of relative update. Using
-:class:`F expressions <django.db.models.F>`, the previous example is expressed
-as:
+assignment of a new value. Django provides :ref:`f-expressions` for performing
+this kind of relative update. Using :ref:`f-expressions`, the previous example
+is expressed as:
 
 .. code-block:: pycon
 
@@ -644,9 +643,8 @@ as:
     >>> product.number_sold = F("number_sold") + 1
     >>> product.save()
 
-For more details, see the documentation on :class:`F expressions
-<django.db.models.F>` and their :ref:`use in update queries
-<topics-db-queries-update>`.
+For more details, see the documentation on :ref:`f-expressions` and their
+:ref:`use in update queries <topics-db-queries-update>`.
 
 .. _ref-models-update-fields:
 
diff --git a/docs/ref/models/meta.txt b/docs/ref/models/meta.txt
index 8aa553f073..4595362a4d 100644
--- a/docs/ref/models/meta.txt
+++ b/docs/ref/models/meta.txt
@@ -38,8 +38,8 @@ Retrieving a single field instance of a model by name
     user, the :attr:`~.ForeignKey.related_name` set by the user, or the name
     automatically generated by Django.
 
-    :attr:`Hidden fields <django.db.models.Field.hidden>` cannot be retrieved
-    by name.
+    Hidden fields, fields with :attr:`hidden=True
+    <django.db.models.Field.hidden>`, cannot be retrieved by name.
 
     If a field with the given name is not found a
     :class:`~django.core.exceptions.FieldDoesNotExist` exception will be
@@ -80,7 +80,7 @@ Retrieving all field instances of a model
 
     ``include_hidden``
         ``False`` by default. If set to ``True``, ``get_fields()`` will include
-        :attr:`hidden fields <django.db.models.Field.hidden>`.
+        fields with :attr:`hidden=True <django.db.models.Field.hidden>`.
 
     .. code-block:: pycon
 
@@ -127,9 +127,8 @@ Retrieving fields composing the primary key of a model
 
     Returns a list of the fields composing the primary key of a model.
 
-    When a :class:`composite primary key
-    <django.db.models.CompositePrimaryKey>` is defined on a model it will
-    contain all the :class:`fields <django.db.models.Field>` referenced by it.
+    When a :class:`~django.db.models.CompositePrimaryKey` is defined on a model
+    it will contain all the fields referenced by it.
 
     .. code-block:: python
 
@@ -149,8 +148,10 @@ Retrieving fields composing the primary key of a model
             <django.db.models.fields.IntegerField: id>
         ]
 
-    Otherwise it will contain the single field declared as the
-    :attr:`primary key <django.db.models.Field.primary_key>` of the model.
+    Otherwise it will contain the single field declared as the primary key of
+    the model, either explicitly with :attr:`primary_key=True
+    <django.db.models.Field.primary_key>` or implicitly as the :ref:`automatic
+    primary key <automatic-primary-key-fields>`.
 
     .. code-block:: pycon
 
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 3e7024211e..e494739bcd 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -209,7 +209,7 @@ The lookup parameters (``**kwargs``) should be in the format described in
 underlying SQL statement.
 
 If you need to execute more complex queries (for example, queries with ``OR``
-statements), you can use :class:`Q objects <django.db.models.Q>` (``*args``).
+statements), you can use :ref:`q-objects` (``*args``).
 
 ``exclude()``
 ~~~~~~~~~~~~~
@@ -259,8 +259,8 @@ statements), you can use :class:`Q objects <django.db.models.Q>` (``*args``).
 .. method:: annotate(*args, **kwargs)
 
 Annotates each object in the ``QuerySet`` with the provided list of :doc:`query
-expressions </ref/models/expressions>` or :class:`~django.db.models.Q` objects.
-Each object can be annotated with:
+expressions </ref/models/expressions>` or :ref:`q-objects`. Each object can be
+annotated with:
 
 * a simple value,  via ``Value()``;
 * a reference to a field on the model (or any related models), via ``F()``;
@@ -1276,9 +1276,9 @@ database.
     :meth:`~django.db.models.fields.related.RelatedManager.create`,
     :meth:`~django.db.models.fields.related.RelatedManager.remove`,
     :meth:`~django.db.models.fields.related.RelatedManager.clear` or
-    :meth:`~django.db.models.fields.related.RelatedManager.set`, on
-    :class:`related managers<django.db.models.fields.related.RelatedManager>`,
-    any prefetched cache for the relation will be cleared.
+    :meth:`~django.db.models.fields.related.RelatedManager.set`, on a
+    :class:`~django.db.models.fields.related.RelatedManager`, any prefetched
+    cache for the relation will be cleared.
 
 You can also use the normal join syntax to do related fields of related
 fields. Suppose we have an additional model to the example above::
@@ -1433,8 +1433,8 @@ where prefetching with a custom ``QuerySet`` is useful:
 
 * You want to prefetch only a subset of the related objects.
 
-* You want to use performance optimization techniques like
-  :meth:`deferred fields <defer()>`:
+* You want to use performance optimization techniques like deferring fields,
+  for example, via :meth:`defer` or :meth:`only`:
 
   .. code-block:: pycon
 
@@ -1797,11 +1797,10 @@ will always be fetched into the resulting queryset.
     normalize your models and put the non-loaded data into a separate model
     (and database table). If the columns *must* stay in the one table for some
     reason, create a model with ``Meta.managed = False`` (see the
-    :attr:`managed attribute <django.db.models.Options.managed>` documentation)
-    containing just the fields you normally need to load and use that where you
-    might otherwise call ``defer()``. This makes your code more explicit to the
-    reader, is slightly faster and consumes a little less memory in the Python
-    process.
+    :attr:`~django.db.models.Options.managed` documentation) containing just
+    the fields you normally need to load and use that where you might otherwise
+    call ``defer()``. This makes your code more explicit to the reader, is
+    slightly faster and consumes a little less memory in the Python process.
 
     For example, both of these models use the same underlying database table::
 
@@ -2266,9 +2265,9 @@ found, ``get_or_create()`` returns a tuple of that object and ``False``.
     inserted.
 
 You can specify more complex conditions for the retrieved object by chaining
-``get_or_create()`` with ``filter()`` and using :class:`Q objects
-<django.db.models.Q>`. For example, to retrieve Robert or Bob Marley if either
-exists, and create the latter otherwise::
+``get_or_create()`` with ``filter()`` and using :ref:`q-objects`. For example,
+to retrieve Robert or Bob Marley if either exists, and create the latter
+otherwise::
 
     from django.db.models import Q
 
@@ -3963,8 +3962,8 @@ An optional argument that represents the :doc:`model field
 ``filter``
 ~~~~~~~~~~
 
-An optional :class:`Q object <django.db.models.Q>` that's used to filter the
-rows that are aggregated.
+An optional :ref:`Q object <q-objects>` that's used to filter the rows that
+are aggregated.
 
 See :ref:`conditional-aggregation` and :ref:`filtering-on-annotations` for
 example usage.
@@ -4178,6 +4177,8 @@ Query-related tools
 This section provides reference material for query-related tools not documented
 elsewhere.
 
+.. _q-objects:
+
 ``Q()`` objects
 ---------------
 
@@ -4282,7 +4283,7 @@ overridden by using a custom queryset in a related lookup.
 
     .. attribute:: FilteredRelation.condition
 
-        A :class:`~django.db.models.Q` object to control the filtering.
+        A :ref:`Q object <q-objects>` to control the filtering.
 
 ``FilteredRelation`` is used with :meth:`~.QuerySet.annotate` to create an
 ``ON`` clause when a ``JOIN`` is performed. It doesn't act on the default