From 01f8460653e73a8f60c98d3a37a74b28818744b6 Mon Sep 17 00:00:00 2001 From: Clifford Gama Date: Wed, 29 Oct 2025 17:32:12 +0200 Subject: 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> --- docs/ref/contrib/auth.txt | 6 ++---- docs/ref/contrib/contenttypes.txt | 12 +++++------ docs/ref/contrib/postgres/search.txt | 6 +++--- docs/ref/django-admin.txt | 6 +++--- docs/ref/models/expressions.txt | 4 +++- docs/ref/models/fields.txt | 12 +++++------ docs/ref/models/indexes.txt | 8 ++++---- docs/ref/models/instances.txt | 12 +++++------ docs/ref/models/meta.txt | 17 ++++++++-------- docs/ref/models/querysets.txt | 39 ++++++++++++++++++------------------ docs/ref/settings.txt | 13 ++++++------ 11 files changed, 67 insertions(+), 68 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index 4438182cb0..ff16de6423 100644 --- a/docs/ref/contrib/auth.txt +++ b/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 - `, - 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 `. Custom user models that don't have an :attr:`~django.contrib.auth.models.CustomUser.is_active` field are allowed. diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index 72bee36a08..9a6b14ef4c 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/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 ` for the model the :class:`~django.contrib.contenttypes.models.ContentType` - represents, and does - :meth:`a get() lookup ` + 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 ` 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 ` 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". diff --git a/docs/ref/contrib/postgres/search.txt b/docs/ref/contrib/postgres/search.txt index 0d14bc8c05..15f4909e0f 100644 --- a/docs/ref/contrib/postgres/search.txt +++ b/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 ` or -:class:`GiST ` 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"), diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 24367e5871..030d2f28dd 100644 --- a/docs/ref/django-admin.txt +++ b/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 ` 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 ` 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) 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 ` that's +The ``filter`` argument takes a :ref:`Q object ` 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 ` 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 ` and :class:`querysets - `. + 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 `, the ``Field`` + When using :doc:`model forms `, 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 - `, and :class:`SP-GiST indexes - `. + 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 `, 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 -` for performing this kind of relative update. Using -:class:`F expressions `, 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 -` and their :ref:`use in update queries -`. +For more details, see the documentation on :ref:`f-expressions` and their +:ref:`use in update queries `. .. _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 ` cannot be retrieved - by name. + Hidden fields, fields with :attr:`hidden=True + `, 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 `. + fields with :attr:`hidden=True `. .. 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 - ` is defined on a model it will - contain all the :class:`fields ` 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 ] - Otherwise it will contain the single field declared as the - :attr:`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 + ` or implicitly as the :ref:`automatic + primary key `. .. 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 ` (``*args``). +statements), you can use :ref:`q-objects` (``*args``). ``exclude()`` ~~~~~~~~~~~~~ @@ -259,8 +259,8 @@ statements), you can use :class:`Q objects ` (``*args``). .. method:: annotate(*args, **kwargs) Annotates each object in the ``QuerySet`` with the provided list of :doc:`query -expressions ` or :class:`~django.db.models.Q` objects. -Each object can be annotated with: +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`, - 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 `: +* 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 ` 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 -`. 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 ` that's used to filter the -rows that are aggregated. +An optional :ref:`Q object ` 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 ` 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 diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index b0750d3a42..8ac7a194f6 100644 --- a/docs/ref/settings.txt +++ b/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 ` 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 ` (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 -- cgit v1.3