[pull] main from django:main

docs/faq/install.txt

@@ -25,10 +25,10 @@ needed.
 For a development environment -- if you just want to experiment with Django --
 you don't need to have a separate web server installed or database server.
 
-Django comes with its own :djadmin:`lightweight development server<runserver>`.
-For a production environment, Django follows the WSGI spec, :pep:`3333`, which
-means it can run on a variety of web servers. See :doc:`Deploying Django
-</howto/deployment/index>` for more information.
+Django comes with its own lightweight development server
+(:djadmin:`runserver`). For a production environment, Django follows the WSGI
+spec, :pep:`3333`, which means it can run on a variety of web servers. See
+:doc:`/howto/deployment/index` for more information.
 
 Django runs `SQLite`_ by default, which is included in Python installations.
 For a production environment, we recommend PostgreSQL_; but we also officially

docs/howto/error-reporting.txt

@@ -195,7 +195,7 @@ filtered out of error reports in a production environment (that is, where
 .. function:: sensitive_post_parameters(*parameters)
 
     If one of your views receives an :class:`~django.http.HttpRequest` object
-    with :attr:`POST parameters<django.http.HttpRequest.POST>` susceptible to
+    with :attr:`~django.http.HttpRequest.POST` parameters susceptible to
     contain sensitive information, you may prevent the values of those
     parameters from being included in the error reports using the
     ``sensitive_post_parameters`` decorator::

docs/howto/logging.txt

@@ -186,9 +186,9 @@ root of the project.
 Configure a formatter
 ~~~~~~~~~~~~~~~~~~~~~
 
-By default, the final log output contains the message part of each :class:`log
-record <logging.LogRecord>`. Use a formatter if you want to include additional
-data. First name and define your formatters - this example defines
+By default, the final log output contains the message part of each
+:class:`~logging.LogRecord` object. Use a formatter if you want to include
+additional data. First name and define your formatters - this example defines
 formatters named ``verbose`` and ``simple``:
 
 .. code-block:: python

docs/intro/tutorial07.txt

@@ -284,13 +284,16 @@ the scenes, limiting the number of search fields to a reasonable number will
 make it easier for your database to do the search.
 
 Now's also a good time to note that change lists give you free pagination. The
-default is to display 100 items per page. :attr:`Change list pagination
-<django.contrib.admin.ModelAdmin.list_per_page>`, :attr:`search boxes
-<django.contrib.admin.ModelAdmin.search_fields>`, :attr:`filters
-<django.contrib.admin.ModelAdmin.list_filter>`, :attr:`date-hierarchies
-<django.contrib.admin.ModelAdmin.date_hierarchy>`, and
-:attr:`column-header-ordering <django.contrib.admin.ModelAdmin.list_display>`
-all work together like you think they should.
+default is to display 100 items per page.
+
+.. seealso::
+
+   The following :class:`~django.contrib.admin.ModelAdmin` options allow
+   further customization of change lists:
+   :attr:`~django.contrib.admin.ModelAdmin.list_per_page`,
+   :attr:`~django.contrib.admin.ModelAdmin.search_fields`,
+   :attr:`~django.contrib.admin.ModelAdmin.date_hierarchy`, and
+   :attr:`~django.contrib.admin.ModelAdmin.list_display`.
 
 Customize the admin look and feel
 =================================

docs/ref/contrib/auth.txt

@@ -646,10 +646,8 @@ The following backends are available in :mod:`django.contrib.auth.backends`:
     .. method:: user_can_authenticate()
 
         Returns whether the user is allowed to authenticate. To match the
-        behavior of :class:`~django.contrib.auth.forms.AuthenticationForm`
-        which :meth:`prohibits inactive users from logging in
-        <django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed>`,
-        this method returns ``False`` for users with :attr:`is_active=False
+        behavior of :meth:`.AuthenticationForm.confirm_login_allowed`, this
+        method returns ``False`` for users with :attr:`is_active=False
         <django.contrib.auth.models.User.is_active>`. Custom user models that
         don't have an :attr:`~django.contrib.auth.models.CustomUser.is_active`
         field are allowed.

docs/ref/contrib/contenttypes.txt

@@ -110,8 +110,7 @@ model it represents, or to retrieve objects from that model:
 
     Takes a set of valid :ref:`lookup arguments <field-lookups-intro>` for the
     model the :class:`~django.contrib.contenttypes.models.ContentType`
-    represents, and does
-    :meth:`a get() lookup <django.db.models.query.QuerySet.get>`
+    represents, and does a :meth:`~django.db.models.query.QuerySet.get` lookup
     on that model, returning the corresponding object. The ``using`` argument
     can be used to specify a different database than the default one.
 
@@ -160,11 +159,10 @@ two extremely important use cases:
    to get access to those model classes.
 
 Several of Django's bundled applications make use of the latter technique.
-For example,
-:class:`the permissions system <django.contrib.auth.models.Permission>` in
-Django's authentication framework uses a
-:class:`~django.contrib.auth.models.Permission` model with a foreign
-key to :class:`~django.contrib.contenttypes.models.ContentType`; this lets
+For example, :ref:`the permissions system <topic-authorization>` in Django's
+authentication framework uses a :class:`~django.contrib.auth.models.Permission`
+model with a foreign key to
+:class:`~django.contrib.contenttypes.models.ContentType`; this lets
 :class:`~django.contrib.auth.models.Permission` represent concepts like
 "can add blog entry" or "can delete news story".
 

docs/ref/contrib/postgres/search.txt

@@ -338,9 +338,9 @@ than comparing the size of an integer, for example.
 
 In the event that all the fields you're querying on are contained within one
 particular model, you can create a functional
-:class:`GIN <django.contrib.postgres.indexes.GinIndex>` or
-:class:`GiST <django.contrib.postgres.indexes.GistIndex>` index which matches
-the search vector you wish to use. For example::
+:class:`~django.contrib.postgres.indexes.GinIndex` or
+:class:`~django.contrib.postgres.indexes.GistIndex` which matches the search
+vector you wish to use. For example::
 
     GinIndex(
         SearchVector("body_text", "headline", config="english"),

docs/ref/django-admin.txt

@@ -1337,8 +1337,8 @@ Specifies which directories in the app template should be excluded, in addition
 to ``.git`` and ``__pycache__``. If this option is not provided, directories
 named ``__pycache__`` or starting with ``.`` will be excluded.
 
-The :class:`template context <django.template.Context>` used for all matching
-files is:
+The template context (see :class:`~django.template.Context`) used for all
+matching files is:
 
 - Any option passed to the ``startapp`` command (among the command's supported
   options)
@@ -1435,7 +1435,7 @@ Specifies which directories in the project template should be excluded, in
 addition to ``.git`` and ``__pycache__``. If this option is not provided,
 directories named ``__pycache__`` or starting with ``.`` will be excluded.
 
-The :class:`template context <django.template.Context>` used is:
+The template context (see :class:`~django.template.Context`) used is:
 
 - Any option passed to the ``startproject`` command (among the command's
   supported options)

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.
 

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)

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

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:
 

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
 

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

docs/ref/settings.txt

@@ -463,9 +463,9 @@ A list of trusted origins for unsafe requests (e.g. ``POST``).
 For requests that include the ``Origin`` header, Django's CSRF protection
 requires that header match the origin present in the ``Host`` header.
 
-For a :meth:`secure <django.http.HttpRequest.is_secure>` unsafe
-request that doesn't include the ``Origin`` header, the request must have a
-``Referer`` header that matches the origin present in the ``Host`` header.
+For a secure (determined by :meth:`~django.http.HttpRequest.is_secure`) unsafe
+request that doesn't include the ``Origin`` header, the request must include a
+``Referer`` header that matches the origin in the ``Host`` header.
 
 These checks prevent, for example, a ``POST`` request from
 ``subdomain.example.com`` from succeeding against ``api.example.com``. If you
@@ -1778,9 +1778,10 @@ Default: ``[]`` (Empty list)
 List of compiled regular expression objects describing URLs that should be
 ignored when reporting HTTP 404 errors via email (see
 :doc:`/howto/error-reporting`). Regular expressions are matched against
-:meth:`request's full paths <django.http.HttpRequest.get_full_path>` (including
-query string, if any). Use this if your site does not provide a commonly
-requested file such as ``favicon.ico`` or ``robots.txt``.
+request's full paths, as returned by
+:meth:`~django.http.HttpRequest.get_full_path` (including any query strings).
+Use this if your site does not provide a commonly requested file such as
+``favicon.ico`` or ``robots.txt``.
 
 This is only used if
 :class:`~django.middleware.common.BrokenLinkEmailsMiddleware` is enabled (see