Skip to content

Commit cd60a67

Browse files
cliff688cliff688
committed
Fixed #35329 -- Removed non-code custom link text when cross-referencing Python objects.
Thanks Bruno Alla and Sarah Boyce for the reviews.
1 parent 994dc6d commit cd60a67

22 files changed

+140
-151
lines changed

‎docs/howto/error-reporting.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -195,10 +195,10 @@ filtered out of error reports in a production environment (that is, where
195195
.. function:: sensitive_post_parameters(*parameters)
196196

197197
If one of your views receives an :class:`~django.http.HttpRequest` object
198-
with :attr:`POST parameters<django.http.HttpRequest.POST>` susceptible to
199-
contain sensitive information, you may prevent the values of those
200-
parameters from being included in the error reports using the
201-
``sensitive_post_parameters`` decorator::
198+
with :attr:`~django.http.HttpRequest.POST` parameters susceptible to contain
199+
sensitive information, you may prevent the values of those parameters from
200+
being included in the error reports using the ``sensitive_post_parameters``
201+
decorator::
202202

203203
from django.views.decorators.debug import sensitive_post_parameters
204204

‎docs/intro/tutorial07.txt‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -284,13 +284,7 @@ scenes, limiting the number of search fields to a reasonable number will make
284284
it easier for your database to do the search.
285285

286286
Now's also a good time to note that change lists give you free pagination. The
287-
default is to display 100 items per page. :attr:`Change list pagination
288-
<django.contrib.admin.ModelAdmin.list_per_page>`, :attr:`search boxes
289-
<django.contrib.admin.ModelAdmin.search_fields>`, :attr:`filters
290-
<django.contrib.admin.ModelAdmin.list_filter>`, :attr:`date-hierarchies
291-
<django.contrib.admin.ModelAdmin.date_hierarchy>`, and
292-
:attr:`column-header-ordering <django.contrib.admin.ModelAdmin.list_display>`
293-
all work together like you think they should.
287+
default is to display 100 items per page.
294288

295289
Customize the admin look and feel
296290
=================================

‎docs/ref/contrib/auth.txt‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -715,10 +715,8 @@ The following backends are available in :mod:`django.contrib.auth.backends`:
715715
.. method:: user_can_authenticate()
716716

717717
Returns whether the user is allowed to authenticate. To match the
718-
behavior of :class:`~django.contrib.auth.forms.AuthenticationForm`
719-
which :meth:`prohibits inactive users from logging in
720-
<django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed>`,
721-
this method returns ``False`` for users with :attr:`is_active=False
718+
behavior of :meth:`.AuthenticationForm.confirm_login_allowed`, this
719+
method returns ``False`` for users with :attr:`is_active=False
722720
<django.contrib.auth.models.User.is_active>`. Custom user models that
723721
don't have an :attr:`~django.contrib.auth.models.CustomUser.is_active`
724722
field are allowed.

‎docs/ref/contrib/contenttypes.txt‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -110,8 +110,7 @@ model it represents, or to retrieve objects from that model:
110110

111111
Takes a set of valid :ref:`lookup arguments <field-lookups-intro>` for the
112112
model the :class:`~django.contrib.contenttypes.models.ContentType`
113-
represents, and does
114-
:meth:`a get() lookup <django.db.models.query.QuerySet.get>`
113+
represents, and does a :meth:`~django.db.models.query.QuerySet.get` lookup
115114
on that model, returning the corresponding object. The ``using`` argument
116115
can be used to specify a different database than the default one.
117116

@@ -160,11 +159,10 @@ two extremely important use cases:
160159
to get access to those model classes.
161160

162161
Several of Django's bundled applications make use of the latter technique.
163-
For example,
164-
:class:`the permissions system <django.contrib.auth.models.Permission>` in
165-
Django's authentication framework uses a
166-
:class:`~django.contrib.auth.models.Permission` model with a foreign
167-
key to :class:`~django.contrib.contenttypes.models.ContentType`; this lets
162+
For example, :ref:`the permissions system <topic-authorization>` in Django's
163+
authentication framework uses a :class:`~django.contrib.auth.models.Permission`
164+
model with a foreign key to
165+
:class:`~django.contrib.contenttypes.models.ContentType`; this lets
168166
:class:`~django.contrib.auth.models.Permission` represent concepts like
169167
"can add blog entry" or "can delete news story".
170168

‎docs/ref/django-admin.txt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1324,8 +1324,8 @@ Specifies which directories in the app template should be excluded, in addition
13241324
to ``.git`` and ``__pycache__``. If this option is not provided, directories
13251325
named ``__pycache__`` or starting with ``.`` will be excluded.
13261326

1327-
The :class:`template context <django.template.Context>` used for all matching
1328-
files is:
1327+
The template context (see :class:`~django.template.Context`) used for all
1328+
matching files is:
13291329

13301330
- Any option passed to the ``startapp`` command (among the command's supported
13311331
options)
@@ -1419,7 +1419,7 @@ Specifies which directories in the project template should be excluded, in
14191419
addition to ``.git`` and ``__pycache__``. If this option is not provided,
14201420
directories named ``__pycache__`` or starting with ``.`` will be excluded.
14211421

1422-
The :class:`template context <django.template.Context>` used is:
1422+
The template context (see :class:`~django.template.Context`) used is:
14231423

14241424
- Any option passed to the ``startproject`` command (among the command's
14251425
supported options)

‎docs/ref/models/expressions.txt‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,8 @@ Built-in Expressions
113113
``django.db.models.aggregates``, but for convenience they're available and
114114
usually imported from :mod:`django.db.models`.
115115

116+
.. _f-expressions:
117+
116118
``F()`` expressions
117119
-------------------
118120

@@ -496,7 +498,7 @@ should be invoked for each distinct value of ``expressions`` (or set of
496498
values, for multiple ``expressions``). The argument is only supported on
497499
aggregates that have :attr:`~Aggregate.allow_distinct` set to ``True``.
498500

499-
The ``filter`` argument takes a :class:`Q object <django.db.models.Q>` that's
501+
The ``filter`` argument takes a :ref:`Q object <q-objects>` that's
500502
used to filter the rows that are aggregated. See :ref:`conditional-aggregation`
501503
and :ref:`filtering-on-annotations` for example usage.
502504

‎docs/ref/models/fields.txt‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -561,8 +561,8 @@ The primary key field is read-only. If you change the value of the primary
561561
key on an existing object and then save it, a new object will be created
562562
alongside the old one.
563563

564-
The primary key field is set to ``None`` when
565-
:meth:`deleting <django.db.models.Model.delete>` an object.
564+
The primary key field is set to ``None`` when calling a model instance’s
565+
:meth:`~django.db.models.Model.delete` method.
566566

567567
.. versionchanged:: 5.2
568568

@@ -2401,9 +2401,9 @@ Field API reference
24012401
Python types to database (:meth:`get_prep_value`) and vice-versa
24022402
(:meth:`from_db_value`).
24032403

2404-
A field is thus a fundamental piece in different Django APIs, notably,
2405-
:class:`models <django.db.models.Model>` and :class:`querysets
2406-
<django.db.models.query.QuerySet>`.
2404+
A field is thus a fundamental piece in various Django APIs, notably the
2405+
:class:`~django.db.models.Model` and the
2406+
:class:`~django.db.models.query.QuerySet` APIs.
24072407

24082408
In models, a field is instantiated as a class attribute and represents a
24092409
particular table column, see :doc:`/topics/db/models`. It has attributes
@@ -2562,7 +2562,7 @@ Field API reference
25622562

25632563
See :ref:`converting-model-field-to-serialization` for usage.
25642564

2565-
When using :class:`model forms <django.forms.ModelForm>`, the ``Field``
2565+
When using :doc:`model forms </topics/forms/modelforms>`, the ``Field``
25662566
needs to know which form field it should be represented by:
25672567

25682568
.. method:: formfield(form_class=None, choices_form_class=None, **kwargs)

‎docs/ref/models/instances.txt‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -635,10 +635,9 @@ the value of 11 will be written back to the database.
635635
The process can be made robust, :ref:`avoiding a race condition
636636
<avoiding-race-conditions-using-f>`, as well as slightly faster by expressing
637637
the update relative to the original field value, rather than as an explicit
638-
assignment of a new value. Django provides :class:`F expressions
639-
<django.db.models.F>` for performing this kind of relative update. Using
640-
:class:`F expressions <django.db.models.F>`, the previous example is expressed
641-
as:
638+
assignment of a new value. Django provides :ref:`f-expressions` for performing
639+
this kind of relative update. Using :ref:`f-expressions`, the previous example
640+
is expressed as:
642641

643642
.. code-block:: pycon
644643

@@ -647,9 +646,8 @@ as:
647646
>>> product.number_sold = F("number_sold") + 1
648647
>>> product.save()
649648

650-
For more details, see the documentation on :class:`F expressions
651-
<django.db.models.F>` and their :ref:`use in update queries
652-
<topics-db-queries-update>`.
649+
For more details, see the documentation on :ref:`f-expressions` and their
650+
:ref:`use in update queries <topics-db-queries-update>`.
653651

654652
.. _ref-models-update-fields:
655653

‎docs/ref/models/meta.txt‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,8 @@ Retrieving a single field instance of a model by name
3838
set by the user, the :attr:`~.ForeignKey.related_name` set by the user, or
3939
the name automatically generated by Django.
4040

41-
:attr:`Hidden fields <django.db.models.Field.hidden>` cannot be retrieved
42-
by name.
41+
Hidden fields (:attr:`hidden=True <django.db.models.Field.hidden>`) cannot
42+
be retrieved by name.
4343

4444
If a field with the given name is not found a
4545
:class:`~django.core.exceptions.FieldDoesNotExist` exception will be
@@ -80,7 +80,7 @@ Retrieving all field instances of a model
8080

8181
``include_hidden``
8282
``False`` by default. If set to ``True``, ``get_fields()`` will include
83-
:attr:`hidden fields <django.db.models.Field.hidden>`.
83+
fields with :attr:`hidden=True<django.db.models.Field.hidden>`.
8484

8585
.. code-block:: pycon
8686

@@ -129,9 +129,9 @@ Retrieving fields composing the primary key of a model
129129

130130
Returns a list of the fields composing the primary key of a model.
131131

132-
When a :class:`composite primary key <django.db.models.CompositePrimaryKey>`
133-
is defined on a model it will contain all the
134-
:class:`fields <django.db.models.Field>` referenced by it.
132+
When a :class:`~django.db.models.CompositePrimaryKey` is defined on a
133+
model it will contain all the :doc:`fields </ref/models/fields>`
134+
referenced by it.
135135

136136
.. code-block:: python
137137

@@ -151,8 +151,10 @@ Retrieving fields composing the primary key of a model
151151
<django.db.models.fields.IntegerField: id>
152152
]
153153

154-
Otherwise it will contain the single field declared as the
155-
:attr:`primary key <django.db.models.Field.primary_key>` of the model.
154+
Otherwise it will contain the single field declared as the primary key of
155+
the model, either explicitly with :attr:`primary_key=True
156+
<django.db.models.Field.primary_key>` or implicitly as the :ref:`automatic
157+
primary key <automatic-primary-key-fields>`.
156158

157159
.. code-block:: pycon
158160

‎docs/ref/models/querysets.txt‎

Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -208,7 +208,7 @@ The lookup parameters (``**kwargs``) should be in the format described in
208208
underlying SQL statement.
209209

210210
If you need to execute more complex queries (for example, queries with ``OR`` statements),
211-
you can use :class:`Q objects <django.db.models.Q>` (``*args``).
211+
you can use :ref:`q-objects` (``*args``).
212212

213213
``exclude()``
214214
~~~~~~~~~~~~~
@@ -250,16 +250,16 @@ In SQL terms, that evaluates to:
250250
Note the second example is more restrictive.
251251

252252
If you need to execute more complex queries (for example, queries with ``OR`` statements),
253-
you can use :class:`Q objects <django.db.models.Q>` (``*args``).
253+
you can use :ref:`q-objects` (``*args``).
254254

255255
``annotate()``
256256
~~~~~~~~~~~~~~
257257

258258
.. method:: annotate(*args, **kwargs)
259259

260260
Annotates each object in the ``QuerySet`` with the provided list of :doc:`query
261-
expressions </ref/models/expressions>` or :class:`~django.db.models.Q` objects.
262-
Each object can be annotated with:
261+
expressions </ref/models/expressions>` or :ref:`q-objects`. Each object can be
262+
annotated with:
263263

264264
* a simple value, via ``Value()``;
265265
* a reference to a field on the model (or any related models), via ``F()``;
@@ -1270,9 +1270,9 @@ database.
12701270
:meth:`~django.db.models.fields.related.RelatedManager.create`,
12711271
:meth:`~django.db.models.fields.related.RelatedManager.remove`,
12721272
:meth:`~django.db.models.fields.related.RelatedManager.clear` or
1273-
:meth:`~django.db.models.fields.related.RelatedManager.set`, on
1274-
:class:`related managers<django.db.models.fields.related.RelatedManager>`,
1275-
any prefetched cache for the relation will be cleared.
1273+
:meth:`~django.db.models.fields.related.RelatedManager.set`, on a
1274+
:class:`~django.db.models.fields.related.RelatedManager`, any prefetched
1275+
cache for the relation will be cleared.
12761276

12771277
You can also use the normal join syntax to do related fields of related
12781278
fields. Suppose we have an additional model to the example above::
@@ -1426,8 +1426,8 @@ where prefetching with a custom ``QuerySet`` is useful:
14261426

14271427
* You want to prefetch only a subset of the related objects.
14281428

1429-
* You want to use performance optimization techniques like
1430-
:meth:`deferred fields <defer()>`:
1429+
* You want to use performance optimization techniques like deferring fields,
1430+
for example, via :meth:`defer` or :meth:`only`:
14311431

14321432
.. code-block:: pycon
14331433

@@ -1790,11 +1790,10 @@ will always be fetched into the resulting queryset.
17901790
normalize your models and put the non-loaded data into a separate model
17911791
(and database table). If the columns *must* stay in the one table for some
17921792
reason, create a model with ``Meta.managed = False`` (see the
1793-
:attr:`managed attribute <django.db.models.Options.managed>` documentation)
1794-
containing just the fields you normally need to load and use that where you
1795-
might otherwise call ``defer()``. This makes your code more explicit to the
1796-
reader, is slightly faster and consumes a little less memory in the Python
1797-
process.
1793+
:attr:`~django.db.models.Options.managed` documentation) containing just
1794+
the fields you normally need to load and use that where you might otherwise
1795+
call ``defer()``. This makes your code more explicit to the reader, is
1796+
slightly faster and consumes a little less memory in the Python process.
17981797

17991798
For example, both of these models use the same underlying database table::
18001799

@@ -2258,9 +2257,9 @@ found, ``get_or_create()`` returns a tuple of that object and ``False``.
22582257
inserted.
22592258

22602259
You can specify more complex conditions for the retrieved object by chaining
2261-
``get_or_create()`` with ``filter()`` and using :class:`Q objects
2262-
<django.db.models.Q>`. For example, to retrieve Robert or Bob Marley if either
2263-
exists, and create the latter otherwise::
2260+
``get_or_create()`` with ``filter()`` and using :ref:`q-objects`. For example,
2261+
to retrieve Robert or Bob Marley if either exists, and create the latter
2262+
otherwise::
22642263

22652264
from django.db.models import Q
22662265

@@ -3923,8 +3922,8 @@ of the return value
39233922
``filter``
39243923
~~~~~~~~~~
39253924

3926-
An optional :class:`Q object <django.db.models.Q>` that's used to filter the
3927-
rows that are aggregated.
3925+
An optional :ref:`Q object <q-objects>` that's used to filter the rows that
3926+
are aggregated.
39283927

39293928
See :ref:`conditional-aggregation` and :ref:`filtering-on-annotations` for
39303929
example usage.
@@ -4084,6 +4083,8 @@ Query-related tools
40844083
This section provides reference material for query-related tools not documented
40854084
elsewhere.
40864085

4086+
.. _q-objects:
4087+
40874088
``Q()`` objects
40884089
---------------
40894090

@@ -4187,7 +4188,7 @@ overridden by using a custom queryset in a related lookup.
41874188

41884189
.. attribute:: FilteredRelation.condition
41894190

4190-
A :class:`~django.db.models.Q` object to control the filtering.
4191+
A :ref:`Q object <q-objects>` to control the filtering.
41914192

41924193
``FilteredRelation`` is used with :meth:`~.QuerySet.annotate()` to create an
41934194
``ON`` clause when a ``JOIN`` is performed. It doesn't act on the default

0 commit comments

Comments
 (0)