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>

11 files changed, 83 insertions, 88 deletions

diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index c4adb1d1fc..f9d216e1df 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -37,8 +37,8 @@ The primary attributes of the default user are:
 * :attr:`~django.contrib.auth.models.User.first_name`
 * :attr:`~django.contrib.auth.models.User.last_name`
 
-See the :class:`full API documentation <django.contrib.auth.models.User>` for
-full reference, the documentation that follows is more task oriented.
+See the :class:`~django.contrib.auth.models.User` API documentation for a
+complete reference. The documentation that follows is more task-oriented.
 
 .. _topics-auth-creating-users:
 
@@ -368,7 +368,7 @@ Authentication in web requests
 ==============================
 
 Django uses :doc:`sessions </topics/http/sessions>` and middleware to hook the
-authentication system into :class:`request objects <django.http.HttpRequest>`.
+authentication system into :class:`~django.http.HttpRequest` objects.
 
 These provide a :attr:`request.user <django.http.HttpRequest.user>`  attribute
 and a :meth:`request.auser <django.http.HttpRequest.auser>` async method
@@ -1619,9 +1619,9 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`:
 .. class:: AdminPasswordChangeForm
 
     A form used in the admin interface to change a user's password, including
-    the ability to set an :meth:`unusable password
-    <django.contrib.auth.models.User.set_unusable_password>`, which blocks the
-    user from logging in with password-based authentication.
+    the ability to set an unusable password (via
+    :meth:`~django.contrib.auth.models.User.set_unusable_password`), which
+    blocks the user from logging in with password-based authentication.
 
     Takes the ``user`` as the first positional argument.
 
diff --git a/docs/topics/class-based-views/mixins.txt b/docs/topics/class-based-views/mixins.txt
index 619636d8b9..bf577972a9 100644
--- a/docs/topics/class-based-views/mixins.txt
+++ b/docs/topics/class-based-views/mixins.txt
@@ -156,12 +156,13 @@ it.
 
 To make a :class:`~django.template.response.TemplateResponse`,
 :class:`ListView` then uses
-:class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`; as
-with :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`
-above, this overrides ``get_template_names()`` to provide :meth:`a range of
-options <django.views.generic.list.MultipleObjectTemplateResponseMixin>`, with
-the most commonly-used being ``<app_label>/<model_name>_list.html``, with the
-``_list`` part again being taken from the
+:class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
+As with :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`
+above, this overrides
+:meth:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.get_template_names`
+to provide a range of options, with the most commonly-used being
+``<app_label>/<model_name>_list.html``, with the ``_list`` part again
+being taken from the
 :attr:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.template_name_suffix`
 attribute. (The date based generic views use suffixes such as ``_archive``,
 ``_archive_year`` and so on to use different templates for the various
diff --git a/docs/topics/composite-primary-key.txt b/docs/topics/composite-primary-key.txt
index 736bed5255..c299e4528a 100644
--- a/docs/topics/composite-primary-key.txt
+++ b/docs/topics/composite-primary-key.txt
@@ -199,8 +199,7 @@ Building composite primary key ready applications
 
 Prior to the introduction of composite primary keys, the single field composing
 the primary key of a model could be retrieved by introspecting the
-:attr:`primary key <django.db.models.Field.primary_key>` attribute of its
-fields:
+:attr:`~django.db.models.Field.primary_key` attribute of its fields:
 
 .. code-block:: pycon
 
@@ -214,10 +213,10 @@ fields:
     <django.db.models.fields.AutoField: id>
 
 Now that a primary key can be composed of multiple fields the
-:attr:`primary key <django.db.models.Field.primary_key>` attribute can no
-longer be relied upon to identify members of the primary key as it will be set
-to ``False`` to maintain the invariant that at most one field per model will
-have this attribute set to ``True``:
+:attr:`~django.db.models.Field.primary_key` attribute can no longer be relied
+upon to identify members of the primary key as it will be set to ``False`` to
+maintain the invariant that at most one field per model will have this
+attribute set to ``True``:
 
 .. code-block:: pycon
 
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index 89870adb32..8c53aa7058 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -968,8 +968,8 @@ See :ref:`ref-models-update-fields` for more details.
 
     Note that the :meth:`~Model.delete` method for an object is not
     necessarily called when :ref:`deleting objects in bulk using a
-    QuerySet <topics-db-queries-delete>` or as a result of a :attr:`cascading
-    delete <django.db.models.ForeignKey.on_delete>`. To ensure customized
+    QuerySet <topics-db-queries-delete>` or as a result of a cascading delete
+    (see :attr:`~django.db.models.ForeignKey.on_delete`). To ensure customized
     delete logic gets executed, you can use
     :data:`~django.db.models.signals.pre_delete` and/or
     :data:`~django.db.models.signals.post_delete` signals.
diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt
index e03c9c6354..9c4ba314ae 100644
--- a/docs/topics/db/optimization.txt
+++ b/docs/topics/db/optimization.txt
@@ -133,8 +133,8 @@ For instance:
 * At the most basic level, use :ref:`filter and exclude <queryset-api>` to do
   filtering in the database.
 
-* Use :class:`F expressions <django.db.models.F>` to filter
-  based on other fields within the same model.
+* Use :ref:`f-expressions` to filter based on other fields within the same
+  model.
 
 * Use :doc:`annotate to do aggregation in the database
   </topics/db/aggregation>`.
@@ -396,9 +396,8 @@ number of SQL queries. For example::
     Entry.objects.create(headline="This is a test")
     Entry.objects.create(headline="This is only a test")
 
-Note that there are a number of :meth:`caveats to this method
-<django.db.models.query.QuerySet.bulk_create>`, so make sure it's appropriate
-for your use case.
+Note that :meth:`~django.db.models.query.QuerySet.bulk_create` has several
+caveats, so ensure it's appropriate for your use case.
 
 Update in bulk
 --------------
@@ -427,9 +426,8 @@ The following example::
     entries[1].headline = "This is no longer a test"
     entries[1].save()
 
-Note that there are a number of :meth:`caveats to this method
-<django.db.models.query.QuerySet.bulk_update>`, so make sure it's appropriate
-for your use case.
+Note that :meth:`~django.db.models.query.QuerySet.bulk_update` has several
+caveats, so ensure it's appropriate for your use case.
 
 Insert in bulk
 --------------
@@ -491,12 +489,12 @@ objects to reduce the number of SQL queries. For example::
 
 ...where ``Band`` and ``Artist`` are models with a many-to-many relationship.
 
-When removing different pairs of objects from :class:`ManyToManyFields
-<django.db.models.ManyToManyField>`, use
-:meth:`~django.db.models.query.QuerySet.delete` on a
-:class:`~django.db.models.Q` expression with multiple
-:attr:`~django.db.models.ManyToManyField.through`  model instances to reduce
-the number of SQL queries. For example::
+When removing multiple many-to-many relationships involving several instances
+of the related models, use the :meth:`~django.db.models.query.QuerySet.delete`
+method on a filtered queryset of the field's
+:attr:`~django.db.models.ManyToManyField.through` model. By combining multiple
+conditions with :ref:`q-objects`, you can delete several relationships in a
+single query. For example::
 
     from django.db.models import Q
 
diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
index ed1d3ea9ed..f6b8717f58 100644
--- a/docs/topics/db/queries.txt
+++ b/docs/topics/db/queries.txt
@@ -541,9 +541,10 @@ is ``'Beatles Blog'``:
 
 This spanning can be as deep as you'd like.
 
-It works backwards, too. While it :attr:`can be customized
-<.ForeignKey.related_query_name>`, by default you refer to a "reverse"
-relationship in a lookup using the lowercase name of the model.
+It works backwards, too. While it can be customized by setting
+:class:`~django.db.models.ForeignKey.related_query_name`, by default you
+refer to a "reverse" relationship in a lookup using the lowercase name of the
+model.
 
 This example retrieves all ``Blog`` objects which have at least one ``Entry``
 whose ``headline`` contains ``'Lennon'``:
@@ -692,10 +693,10 @@ In the examples given so far, we have constructed filters that compare
 the value of a model field with a constant. But what if you want to compare
 the value of a model field with another field on the same model?
 
-Django provides :class:`F expressions <django.db.models.F>` to allow such
-comparisons. Instances of ``F()`` act as a reference to a model field within a
-query. These references can then be used in query filters to compare the values
-of two different fields on the same model instance.
+Django provides :ref:`f-expressions` to allow such comparisons. Instances of
+``F()`` act as a reference to a model field within a query. These references
+can then be used in query filters to compare the values of two different fields
+on the same model instance.
 
 For example, to find a list of all blog entries that have had more comments
 than pingbacks, we construct an ``F()`` object to reference the pingback count,
@@ -1370,12 +1371,11 @@ Complex lookups with ``Q`` objects
 
 Keyword argument queries -- in :meth:`~django.db.models.query.QuerySet.filter`,
 etc. -- are "AND"ed together. If you need to execute more complex queries (for
-example, queries with ``OR`` statements), you can use
-:class:`Q objects <django.db.models.Q>`.
+example, queries with ``OR`` statements), you can use :ref:`q-objects`.
 
-A :class:`Q object <django.db.models.Q>` (``django.db.models.Q``) is an object
-used to encapsulate a collection of keyword arguments. These keyword arguments
-are specified as in "Field lookups" above.
+A :ref:`Q object <q-objects>` (``django.db.models.Q``) is an object used to
+encapsulate a collection of keyword arguments. These keyword arguments are
+specified as in "Field lookups" above.
 
 For example, this ``Q`` object encapsulates a single ``LIKE`` query::
 
@@ -1659,10 +1659,10 @@ them and call :meth:`~django.db.models.Model.save`::
     for item in my_queryset:
         item.save()
 
-Calls to update can also use :class:`F expressions <django.db.models.F>` to
-update one field based on the value of another field in the model. This is
-especially useful for incrementing counters based upon their current value. For
-example, to increment the pingback count for every entry in the blog:
+Calls to update can also use :ref:`f-expressions` to update one field based on
+the value of another field in the model. This is especially useful for
+incrementing counters based upon their current value. For example, to increment
+the pingback count for every entry in the blog:
 
 .. code-block:: pycon
 
diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt
index b3ea14dc27..28597464a3 100644
--- a/docs/topics/forms/formsets.txt
+++ b/docs/topics/forms/formsets.txt
@@ -50,8 +50,9 @@ following example will create a formset class to display two blank forms:
 
 Formsets can be iterated and indexed, accessing forms in the order they were
 created. You can reorder the forms by overriding the default
-:meth:`iteration <object.__iter__>` and
-:meth:`indexing <object.__getitem__>` behavior if needed.
+:meth:`~object.__iter__` and :meth:`~object.__getitem__` methods if needed.
+(For more information on implementing these methods, see the
+:term:`Python documentation on sequences <sequence>`.)
 
 .. _formsets-initial-data:
 
diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index a673a179f6..c46412654c 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -299,14 +299,14 @@ for more information on the model's ``clean()`` hook.
 Considerations regarding model's ``error_messages``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Error messages defined at the
-:attr:`form field <django.forms.Field.error_messages>` level or at the
+Error messages defined at the form field level (
+:attr:`django.forms.Field.error_messages`) or at the
 :ref:`form Meta <modelforms-overriding-default-fields>` level always take
-precedence over the error messages defined at the
-:attr:`model field <django.db.models.Field.error_messages>` level.
+precedence over the error messages defined at the model field level
+(:attr:`django.db.models.Field.error_messages`).
 
-Error messages  defined on :attr:`model fields
-<django.db.models.Field.error_messages>` are only used when the
+Error messages defined on model fields
+(:attr:`django.db.models.Field.error_messages`) are only used when the
 ``ValidationError`` is raised during the :ref:`model validation
 <validating-objects>` step and no corresponding error messages are defined at
 the form level.
diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index dfab9a5f5b..300cf2041c 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -206,7 +206,7 @@ Arguments
     the object.
 
 ``*args``
-    :class:`Q objects <django.db.models.Q>`.
+    :ref:`q-objects`.
 
 ``**kwargs``
     Lookup parameters, which should be in the format accepted by ``get()`` and
@@ -286,7 +286,7 @@ Arguments
     list.
 
 ``*args``
-    :class:`Q objects <django.db.models.Q>`.
+    :ref:`q-objects`.
 
 ``**kwargs``
     Lookup parameters, which should be in the format accepted by ``get()`` and
diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index 560aa476a1..1243789ec7 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -1043,7 +1043,7 @@ The ``JavaScriptCatalog`` view
 
     .. attribute:: packages
 
-        A list of :attr:`application names <django.apps.AppConfig.name>` among
+        A list of application names (:attr:`.AppConfig.name`) among the
         installed applications. Those apps should contain a ``locale``
         directory. All those catalogs plus all catalogs found in
         :setting:`LOCALE_PATHS` (which are always included) are merged into one
diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index b2b89556bd..eda1849334 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -801,26 +801,21 @@ A subclass of :class:`unittest.TestCase` that adds this functionality:
 
 * Some useful assertions like:
 
-  * Checking that a callable :meth:`raises a certain exception
-    <SimpleTestCase.assertRaisesMessage>`.
-  * Checking that a callable :meth:`triggers a certain warning
-    <SimpleTestCase.assertWarnsMessage>`.
-  * Testing form field :meth:`rendering and error treatment
-    <SimpleTestCase.assertFieldOutput>`.
-  * Testing :meth:`HTML responses for the presence/lack of a given fragment
-    <SimpleTestCase.assertContains>`.
-  * Verifying that a template :meth:`has/hasn't been used to generate a given
-    response content <SimpleTestCase.assertTemplateUsed>`.
-  * Verifying that two :meth:`URLs <SimpleTestCase.assertURLEqual>` are equal.
-  * Verifying an HTTP :meth:`redirect <SimpleTestCase.assertRedirects>` is
-    performed by the app.
-  * Robustly testing two :meth:`HTML fragments
-    <SimpleTestCase.assertHTMLEqual>` for equality/inequality or
-    :meth:`containment <SimpleTestCase.assertInHTML>`.
-  * Robustly testing two :meth:`XML fragments <SimpleTestCase.assertXMLEqual>`
-    for equality/inequality.
-  * Robustly testing two :meth:`JSON fragments
-    <SimpleTestCase.assertJSONEqual>` for equality.
+  =========================================== ======================================
+  Assertion                                   What it checks
+  =========================================== ======================================
+  :meth:`~SimpleTestCase.assertRaisesMessage` That a callable raises a certain exception
+  :meth:`~SimpleTestCase.assertWarnsMessage`  That a callable triggers a certain warning
+  :meth:`~SimpleTestCase.assertFieldOutput`   Form field rendering and error output
+  :meth:`~SimpleTestCase.assertContains`      Presence or absence of HTML fragments
+  :meth:`~SimpleTestCase.assertTemplateUsed`  Template usage in a response
+  :meth:`~SimpleTestCase.assertURLEqual`      That two URLs are equal
+  :meth:`~SimpleTestCase.assertRedirects`     That an HTTP redirect occurred
+  :meth:`~SimpleTestCase.assertHTMLEqual`     HTML fragment equality
+  :meth:`~SimpleTestCase.assertInHTML`        HTML fragment containment
+  :meth:`~SimpleTestCase.assertXMLEqual`      XML fragment equality or inequality
+  :meth:`~SimpleTestCase.assertJSONEqual`     JSON fragment equality
+  =========================================== ======================================
 
 * The ability to run tests with :ref:`modified settings <overriding-settings>`.
 * Using the :attr:`~SimpleTestCase.client` :class:`~django.test.Client`.
@@ -1688,7 +1683,7 @@ your test suite.
 
 .. method:: SimpleTestCase.assertContains(response, text, count=None, status_code=200, msg_prefix='', html=False)
 
-    Asserts that a :class:`response <django.http.HttpResponse>` produced the
+    Asserts that an :class:`~django.http.HttpResponse` produced the
     given :attr:`~django.http.HttpResponse.status_code` and that ``text``
     appears in its :attr:`~django.http.HttpResponse.content`. If ``count``
     is provided, ``text`` must occur exactly ``count`` times in the response.
@@ -1701,7 +1696,7 @@ your test suite.
 
 .. method:: SimpleTestCase.assertNotContains(response, text, status_code=200, msg_prefix='', html=False)
 
-    Asserts that a :class:`response <django.http.HttpResponse>` produced the
+    Asserts that an :class:`~django.http.HttpResponse` produced the
     given :attr:`~django.http.HttpResponse.status_code` and that ``text`` does
     *not* appear in its :attr:`~django.http.HttpResponse.content`.
 
@@ -1716,8 +1711,8 @@ your test suite.
     Asserts that the template with the given name was used in rendering the
     response.
 
-    ``response`` must be a response instance returned by the
-    :class:`test client <django.test.Response>`.
+    ``response`` must be a :class:`~django.test.Response` instance returned by
+    the test client.
 
     ``template_name`` should be a string such as ``'admin/index.html'``.
 
@@ -1749,9 +1744,10 @@ your test suite.
 
 .. method:: SimpleTestCase.assertRedirects(response, expected_url, status_code=302, target_status_code=200, msg_prefix='', fetch_redirect_response=True)
 
-    Asserts that the :class:`response <django.http.HttpResponse>` returned a
-    :attr:`~django.http.HttpResponse.status_code` redirect status, redirected
-    to ``expected_url`` (including any ``GET`` data), and that the final page
+    Asserts that the :class:`~django.http.HttpResponse` returned a response
+    with a redirect status (based on its
+    :attr:`~django.http.HttpResponse.status_code`), redirected to
+    ``expected_url`` (including any ``GET`` data), and that the final response
     was received with ``target_status_code``.
 
     If your request used the ``follow`` argument, the ``expected_url`` and