[4.2.x] Refs #34140 -- Corrected rst code-block and various formatting issues in docs.

Backport of ba755ca13123d2691a0926ddb64e5d0a2906a880 from main

17 files changed, 155 insertions, 131 deletions

diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt
index 7649f86132..916c309edd 100644
--- a/docs/ref/applications.txt
+++ b/docs/ref/applications.txt
@@ -76,9 +76,9 @@ Alternatively, :setting:`INSTALLED_APPS` may contain the dotted path to a
 configuration class to specify it explicitly::
 
     INSTALLED_APPS = [
-        ...
+        ...,
         'polls.apps.PollsAppConfig',
-        ...
+        ...,
     ]
 
 For application authors
diff --git a/docs/ref/clickjacking.txt b/docs/ref/clickjacking.txt
index a50e5ab11f..6f505e2fae 100644
--- a/docs/ref/clickjacking.txt
+++ b/docs/ref/clickjacking.txt
@@ -58,9 +58,9 @@ To set the same ``X-Frame-Options`` value for all responses in your site, put
 :setting:`MIDDLEWARE`::
 
     MIDDLEWARE = [
-        ...
+        ...,
         'django.middleware.clickjacking.XFrameOptionsMiddleware',
-        ...
+        ...,
     ]
 
 This middleware is enabled in the settings file generated by
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 718f25411b..22082812c0 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -722,6 +722,8 @@ subclass::
       like::
 
           @admin.display(ordering='-first_name')
+          def colored_first_name(self):
+              ...
 
       The ``ordering`` argument supports query lookups to sort by values on
       related models. This example includes an "author first name" column in
@@ -752,7 +754,8 @@ subclass::
               def full_name(self):
                   return self.first_name + ' ' + self.last_name
 
-    * Elements of ``list_display`` can also be properties::
+    * Elements of ``list_display`` can also be properties
+      ::
 
           class Person(models.Model):
               first_name = models.CharField(max_length=50)
@@ -3028,9 +3031,9 @@ returns a site instance.
     :caption: ``myproject/settings.py``
 
     INSTALLED_APPS = [
-        ...
+        # ...
         'myproject.apps.MyAdminConfig',  # replaces 'django.contrib.admin'
-        ...
+        # ...
     ]
 
 .. _multiple-admin-sites:
diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt
index e23bc5afb3..6f6a3cc27a 100644
--- a/docs/ref/contrib/gis/db-api.txt
+++ b/docs/ref/contrib/gis/db-api.txt
@@ -139,7 +139,7 @@ Geometry Lookups
 Geographic queries with geometries take the following general form (assuming
 the ``Zipcode`` model used in the :doc:`model-api`):
 
-.. code-block:: pycon
+.. code-block:: text
 
     >>> qs = Zipcode.objects.filter(<field>__<lookup_type>=<parameter>)
     >>> qs = Zipcode.objects.exclude(...)
@@ -175,7 +175,7 @@ band index can be specified.
 This results in the following general form for lookups involving rasters
 (assuming the ``Elevation`` model used in the :doc:`model-api`):
 
-.. code-block:: pycon
+.. code-block:: text
 
     >>> qs = Elevation.objects.filter(<field>__<lookup_type>=<parameter>)
     >>> qs = Elevation.objects.filter(<field>__<band_index>__<lookup_type>=<parameter>)
diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt
index 6100bc2698..6dfa2b4e48 100644
--- a/docs/ref/contrib/gis/gdal.txt
+++ b/docs/ref/contrib/gis/gdal.txt
@@ -1007,15 +1007,15 @@ Coordinate System Objects
         >>> proj = '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs '
         >>> wgs84 = SpatialReference(proj) # PROJ string
         >>> wgs84 = SpatialReference("""GEOGCS["WGS 84",
-        DATUM["WGS_1984",
-             SPHEROID["WGS 84",6378137,298.257223563,
-                 AUTHORITY["EPSG","7030"]],
-             AUTHORITY["EPSG","6326"]],
-         PRIMEM["Greenwich",0,
-             AUTHORITY["EPSG","8901"]],
-         UNIT["degree",0.01745329251994328,
-             AUTHORITY["EPSG","9122"]],
-         AUTHORITY["EPSG","4326"]]""") # OGC WKT
+        ... DATUM["WGS_1984",
+        ...      SPHEROID["WGS 84",6378137,298.257223563,
+        ...          AUTHORITY["EPSG","7030"]],
+        ...      AUTHORITY["EPSG","6326"]],
+        ... PRIMEM["Greenwich",0,
+        ...      AUTHORITY["EPSG","8901"]],
+        ... UNIT["degree",0.01745329251994328,
+        ...      AUTHORITY["EPSG","9122"]],
+        ... AUTHORITY["EPSG","4326"]]""") # OGC WKT
 
     .. method:: __getitem__(target)
 
@@ -1025,7 +1025,7 @@ Coordinate System Objects
 
     .. code-block:: pycon
 
-        >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]')
+        >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]'
         >>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326
         >>> print(srs['GEOGCS'])
         WGS 84
diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt
index 42f0e82d83..b13ae1c8af 100644
--- a/docs/ref/contrib/gis/geoquerysets.txt
+++ b/docs/ref/contrib/gis/geoquerysets.txt
@@ -702,11 +702,13 @@ Distance Lookups
 For an overview on performing distance queries, please refer to
 the :ref:`distance queries introduction <distance-queries>`.
 
-Distance lookups take the following form::
+Distance lookups take the following form:
 
-    <field>__<distance lookup>=(<geometry/raster>, <distance value>[, 'spheroid'])
-    <field>__<distance lookup>=(<raster>, <band_index>, <distance value>[, 'spheroid'])
-    <field>__<band_index>__<distance lookup>=(<raster>, <band_index>, <distance value>[, 'spheroid'])
+.. code-block:: text
+
+    <field>__<distance lookup>=(<geometry/raster>, <distance value>[, "spheroid"])
+    <field>__<distance lookup>=(<raster>, <band_index>, <distance value>[, "spheroid"])
+    <field>__<band_index>__<distance lookup>=(<raster>, <band_index>, <distance value>[, "spheroid"])
 
 The value passed into a distance lookup is a tuple; the first two
 values are mandatory, and are the geometry to calculate distances to,
diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt
index 8c2628c750..1347746897 100644
--- a/docs/ref/contrib/gis/geos.txt
+++ b/docs/ref/contrib/gis/geos.txt
@@ -828,7 +828,7 @@ Other Properties & Methods
     .. code-block:: pycon
 
         >>> if poly_1.area > poly_2.area:
-        >>>     pass
+        ...     pass
 
 .. _geos-geometry-collections:
 
diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt
index c0548159fe..29ddf14b3d 100644
--- a/docs/ref/contrib/gis/layermapping.txt
+++ b/docs/ref/contrib/gis/layermapping.txt
@@ -70,9 +70,10 @@ Example
 
     >>> from django.contrib.gis.utils import LayerMapping
     >>> from geoapp.models import TestGeo
-    >>> mapping = {'name' : 'str', # The 'name' model field maps to the 'str' layer field.
-                   'poly' : 'POLYGON', # For geometry fields use OGC name.
-                   } # The mapping is a dictionary
+    >>> mapping = {
+    ...     'name': 'str', # The 'name' model field maps to the 'str' layer field.
+    ...     'poly': 'POLYGON', # For geometry fields use OGC name.
+    ... } # The mapping is a dictionary
     >>> lm = LayerMapping(TestGeo, 'test_poly.shp', mapping)
     >>> lm.save(verbose=True) # Save the layermap, imports the data.
     Saved: Name: 1
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 0885af35e1..7fe1f823b4 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -584,7 +584,6 @@ Here's a sample configuration which uses a MySQL option file::
         }
     }
 
-
 .. code-block:: ini
 
     # my.cnf
@@ -1026,14 +1025,14 @@ using RAC or pluggable databases without ``tnsnames.ora``, for example.
 
 Example of an Easy Connect string::
 
-    'NAME': 'localhost:1521/orclpdb1',
+    'NAME': 'localhost:1521/orclpdb1'
 
 Example of a full DSN string::
 
     'NAME': (
         '(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))'
         '(CONNECT_DATA=(SERVICE_NAME=orclpdb1)))'
-    ),
+    )
 
 Threaded option
 ---------------
@@ -1044,7 +1043,7 @@ the ``threaded`` option of your Oracle database configuration to ``True``::
 
     'OPTIONS': {
         'threaded': True,
-    },
+    }
 
 Failure to do this may result in crashes and other odd behavior.
 
@@ -1060,7 +1059,7 @@ The ``RETURNING INTO`` clause can be disabled by setting the
 
     'OPTIONS': {
         'use_returning_into': False,
-    },
+    }
 
 In this case, the Oracle backend will use a separate ``SELECT`` query to
 retrieve ``AutoField`` values.
@@ -1169,7 +1168,7 @@ file::
     DATABASES = {
         'default': {
             'ENGINE': 'mydbengine',
-            ...
+            # ...
         },
     }
 
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 99a140ad0e..d91dc90a6b 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -1471,7 +1471,7 @@ need to bind the file data containing the mugshot image:
     ...         'message': 'Hi there',
     ...         'sender': 'foo@example.com',
     ...         'cc_myself': True}
-    >>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)}
+    >>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', b"file data")}
     >>> f = ContactFormWithMugshot(data, file_data)
 
 In practice, you will usually specify ``request.FILES`` as the source
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index c685775e5e..1449ab0f30 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -267,7 +267,7 @@ fields. We've specified ``auto_id=False`` to simplify the output:
     <tr><th>Message:</th><td><input type="text" name="message" required></td></tr>
     <tr><th>Sender:</th><td><input type="email" name="sender" required><br>A valid email address, please.</td></tr>
     <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself"></td></tr>
-    >>> print(f.as_ul()))
+    >>> print(f.as_ul())
     <li>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></li>
     <li>Message: <input type="text" name="message" required></li>
     <li>Sender: <input type="email" name="sender" required> A valid email address, please.</li>
@@ -764,7 +764,7 @@ For each field, we describe the default widget used if you don't specify
         >>> from django.core.files.uploadedfile import SimpleUploadedFile
         >>> class ImageForm(forms.Form):
         ...     img = forms.ImageField()
-        >>> file_data = {'img': SimpleUploadedFile('test.png', <file data>)}
+        >>> file_data = {'img': SimpleUploadedFile('test.png', b"file data")}
         >>> form = ImageForm({}, file_data)
         # Pillow closes the underlying file descriptor.
         >>> form.is_valid()
diff --git a/docs/ref/logging.txt b/docs/ref/logging.txt
index edd9f21ecb..c21bd67a70 100644
--- a/docs/ref/logging.txt
+++ b/docs/ref/logging.txt
@@ -228,17 +228,21 @@ logger, but only to the ``django.security`` logger.
 To silence a particular type of ``SuspiciousOperation``, you can override that
 specific logger following this example::
 
-    'handlers': {
-        'null': {
-            'class': 'logging.NullHandler',
+    LOGGING = {
+        # ...
+        'handlers': {
+            'null': {
+                'class': 'logging.NullHandler',
+            },
         },
-    },
-    'loggers': {
-        'django.security.DisallowedHost': {
-            'handlers': ['null'],
-            'propagate': False,
+        'loggers': {
+            'django.security.DisallowedHost': {
+                'handlers': ['null'],
+                'propagate': False,
+            },
         },
-    },
+        # ...
+    }
 
 Other ``django.security`` loggers not based on ``SuspiciousOperation`` are:
 
@@ -286,7 +290,7 @@ Python logging module <python:logging.handlers>`.
                 'class': 'django.utils.log.AdminEmailHandler',
                 'include_html': True,
             },
-        },
+        }
 
     Be aware of the :ref:`security implications of logging
     <logging-security-implications>` when using the ``AdminEmailHandler``.
@@ -301,7 +305,7 @@ Python logging module <python:logging.handlers>`.
                 'class': 'django.utils.log.AdminEmailHandler',
                 'email_backend': 'django.core.mail.backends.filebased.EmailBackend',
             },
-        },
+        }
 
     By default, an instance of the email backend specified in
     :setting:`EMAIL_BACKEND` will be used.
@@ -318,7 +322,7 @@ Python logging module <python:logging.handlers>`.
                 'include_html': True,
                 'reporter_class': 'somepackage.error_reporter.CustomErrorReporter',
             },
-        },
+        }
 
     .. method:: send_mail(subject, message, *args, **kwargs)
 
@@ -354,19 +358,23 @@ logging module.
 
     and then add it to your logging config::
 
-        'filters': {
-            'skip_unreadable_posts': {
-                '()': 'django.utils.log.CallbackFilter',
-                'callback': skip_unreadable_post,
+        LOGGING = {
+            # ...
+            'filters': {
+                'skip_unreadable_posts': {
+                    '()': 'django.utils.log.CallbackFilter',
+                    'callback': skip_unreadable_post,
+                },
             },
-        },
-        'handlers': {
-            'mail_admins': {
-                'level': 'ERROR',
-                'filters': ['skip_unreadable_posts'],
-                'class': 'django.utils.log.AdminEmailHandler',
+            'handlers': {
+                'mail_admins': {
+                    'level': 'ERROR',
+                    'filters': ['skip_unreadable_posts'],
+                    'class': 'django.utils.log.AdminEmailHandler',
+                },
             },
-        },
+            # ...
+        }
 
 .. class:: RequireDebugFalse()
 
@@ -376,18 +384,22 @@ logging module.
     configuration to ensure that the :class:`AdminEmailHandler` only sends
     error emails to admins when :setting:`DEBUG` is ``False``::
 
-        'filters': {
-            'require_debug_false': {
-                '()': 'django.utils.log.RequireDebugFalse',
+        LOGGING = {
+            # ...
+            'filters': {
+                'require_debug_false': {
+                    '()': 'django.utils.log.RequireDebugFalse',
+                },
             },
-        },
-        'handlers': {
-            'mail_admins': {
-                'level': 'ERROR',
-                'filters': ['require_debug_false'],
-                'class': 'django.utils.log.AdminEmailHandler',
+            'handlers': {
+                'mail_admins': {
+                    'level': 'ERROR',
+                    'filters': ['require_debug_false'],
+                    'class': 'django.utils.log.AdminEmailHandler',
+                },
             },
-        },
+            # ...
+        }
 
 .. class:: RequireDebugTrue()
 
diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt
index f6d597a266..765a988d08 100644
--- a/docs/ref/models/database-functions.txt
+++ b/docs/ref/models/database-functions.txt
@@ -1905,7 +1905,9 @@ more frequently.
 .. class:: PercentRank(*expressions, **extra)
 
 Computes the relative rank of the rows in the frame clause. This computation is
-equivalent to evaluating::
+equivalent to evaluating:
+
+.. code-block:: text
 
     (rank - 1) / (total rows - 1)
 
diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index 6a59822e8e..d2f2d0e8b9 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -21,20 +21,20 @@ constants, variables, and even other expressions.
 Some examples
 =============
 
-.. code-block:: python
+.. code-block:: pycon
 
-    from django.db.models import Count, F, Value
-    from django.db.models.functions import Length, Upper
-    from django.db.models.lookups import GreaterThan
+    >>> from django.db.models import Count, F, Value
+    >>> from django.db.models.functions import Length, Upper
+    >>> from django.db.models.lookups import GreaterThan
 
     # Find companies that have more employees than chairs.
-    Company.objects.filter(num_employees__gt=F('num_chairs'))
+    >>> Company.objects.filter(num_employees__gt=F('num_chairs'))
 
     # Find companies that have at least twice as many employees
     # as chairs. Both the querysets below are equivalent.
-    Company.objects.filter(num_employees__gt=F('num_chairs') * 2)
-    Company.objects.filter(
-        num_employees__gt=F('num_chairs') + F('num_chairs'))
+    >>> Company.objects.filter(num_employees__gt=F('num_chairs') * 2)
+    >>> Company.objects.filter(
+    ...     num_employees__gt=F('num_chairs') + F('num_chairs'))
 
     # How many chairs are needed for each company to seat all employees?
     >>> company = Company.objects.filter(
@@ -817,12 +817,12 @@ the same studio in the same genre and release year:
 
     >>> from django.db.models import Avg, F, Window
     >>> Movie.objects.annotate(
-    >>>     avg_rating=Window(
-    >>>         expression=Avg('rating'),
-    >>>         partition_by=[F('studio'), F('genre')],
-    >>>         order_by='released__year',
-    >>>     ),
-    >>> )
+    ...     avg_rating=Window(
+    ...         expression=Avg('rating'),
+    ...         partition_by=[F('studio'), F('genre')],
+    ...         order_by='released__year',
+    ...     ),
+    ... )
 
 This allows you to check if a movie is rated better or worse than its peers.
 
@@ -837,20 +837,20 @@ to reduce repetition:
 
     >>> from django.db.models import Avg, F, Max, Min, Window
     >>> window = {
-    >>>    'partition_by': [F('studio'), F('genre')],
-    >>>    'order_by': 'released__year',
-    >>> }
+    ...    'partition_by': [F('studio'), F('genre')],
+    ...    'order_by': 'released__year',
+    ... }
     >>> Movie.objects.annotate(
-    >>>     avg_rating=Window(
-    >>>         expression=Avg('rating'), **window,
-    >>>     ),
-    >>>     best=Window(
-    >>>         expression=Max('rating'), **window,
-    >>>     ),
-    >>>     worst=Window(
-    >>>         expression=Min('rating'), **window,
-    >>>     ),
-    >>> )
+    ...     avg_rating=Window(
+    ...         expression=Avg('rating'), **window,
+    ...     ),
+    ...     best=Window(
+    ...         expression=Max('rating'), **window,
+    ...     ),
+    ...     worst=Window(
+    ...         expression=Min('rating'), **window,
+    ...     ),
+    ... )
 
 Filtering against window functions is supported as long as lookups are not
 disjunctive (not using ``OR`` or ``XOR`` as a connector) and against a queryset
@@ -864,13 +864,13 @@ from groups to be included:
 .. code-block:: pycon
 
     >>> qs = Movie.objects.annotate(
-    >>>     category_rank=Window(
-    >>>         Rank(), partition_by='category', order_by='-rating'
-    >>>     ),
-    >>>     scenes_count=Count('actors'),
-    >>> ).filter(
-    >>>     Q(category_rank__lte=3) | Q(title__contains='Batman')
-    >>> )
+    ...     category_rank=Window(
+    ...         Rank(), partition_by='category', order_by='-rating'
+    ...     ),
+    ...     scenes_count=Count('actors'),
+    ... ).filter(
+    ...     Q(category_rank__lte=3) | Q(title__contains='Batman')
+    ... )
     >>> list(qs)
     NotImplementedError: Heterogeneous disjunctive predicates against window functions
     are not implemented when performing conditional aggregation.
@@ -949,13 +949,13 @@ with the average rating of a movie's two prior and two following peers:
 
     >>> from django.db.models import Avg, F, RowRange, Window
     >>> Movie.objects.annotate(
-    >>>     avg_rating=Window(
-    >>>         expression=Avg('rating'),
-    >>>         partition_by=[F('studio'), F('genre')],
-    >>>         order_by='released__year',
-    >>>         frame=RowRange(start=-2, end=2),
-    >>>     ),
-    >>> )
+    ...     avg_rating=Window(
+    ...         expression=Avg('rating'),
+    ...         partition_by=[F('studio'), F('genre')],
+    ...         order_by='released__year',
+    ...         frame=RowRange(start=-2, end=2),
+    ...     ),
+    ... )
 
 If the database supports it, you can specify the start and end points based on
 values of an expression in the partition. If the ``released`` field of the
@@ -967,13 +967,13 @@ released between twelve months before and twelve months after the each movie:
 
     >>> from django.db.models import Avg, F, ValueRange, Window
     >>> Movie.objects.annotate(
-    >>>     avg_rating=Window(
-    >>>         expression=Avg('rating'),
-    >>>         partition_by=[F('studio'), F('genre')],
-    >>>         order_by='released__year',
-    >>>         frame=ValueRange(start=-12, end=12),
-    >>>     ),
-    >>> )
+    ...     avg_rating=Window(
+    ...         expression=Avg('rating'),
+    ...         partition_by=[F('studio'), F('genre')],
+    ...         order_by='released__year',
+    ...         frame=ValueRange(start=-12, end=12),
+    ...     ),
+    ... )
 
 .. currentmodule:: django.db.models
 
diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt
index d56b0fb33e..495c3164ee 100644
--- a/docs/ref/models/relations.txt
+++ b/docs/ref/models/relations.txt
@@ -24,7 +24,8 @@ Related objects reference
       In the above example, the methods below will be available on
       the manager ``blog.entry_set``.
 
-    * Both sides of a :class:`~django.db.models.ManyToManyField` relation::
+    * Both sides of a :class:`~django.db.models.ManyToManyField` relation
+      ::
 
             class Topping(models.Model):
                 # ...
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 99a7447e91..bfdd0abc24 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -499,7 +499,7 @@ Use of both ``and`` and ``or`` clauses within the same tag is allowed, with
 
 will be interpreted like:
 
-.. code-block:: python
+.. code-block:: pycon
 
     if (athlete_list and coach_list) or cheerleader_list
 
@@ -1118,14 +1118,16 @@ Example usage:
 
 This example would return this HTML::
 
-    <h1>José Mourinho</h1>
-    <p class="odd">Thibaut Courtois</p>
-    <p class="even">John Terry</p>
-    <p class="odd">Eden Hazard</p>
+.. code-block:: html
+
+    <h1>Gareth</h1>
+    <p class="odd">Harry</p>
+    <p class="even">John</p>
+    <p class="odd">Nick</p>
 
-    <h1>Carlo Ancelotti</h1>
-    <p class="odd">Manuel Neuer</p>
-    <p class="even">Thomas Müller</p>
+    <h1>John</h1>
+    <p class="odd">Andrea</p>
+    <p class="even">Melissa</p>
 
 Notice how the first block ends with ``class="odd"`` and the new one starts
 with ``class="odd"``. Without the ``{% resetcycle %}`` tag, the second block
@@ -1264,6 +1266,8 @@ such as this:
 
 ...then, in a template, you can create a link to this view like this::
 
+.. code-block:: html+django
+
     {% url 'app-views-client' client.id %}
 
 The template tag will output the string ``/clients/client/123/``.
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 75e68aeed2..a9f7dcecbf 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -544,14 +544,14 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
 
         from django.utils.functional import keep_lazy, keep_lazy_text
 
-        def fancy_utility_function(s, ...):
+        def fancy_utility_function(s, *args, **kwargs):
             # Do some conversion on string 's'
             ...
         fancy_utility_function = keep_lazy(str)(fancy_utility_function)
 
         # Or more succinctly:
         @keep_lazy(str)
-        def fancy_utility_function(s, ...):
+        def fancy_utility_function(s, *args, **kwargs):
             ...
 
     The ``keep_lazy()`` decorator takes a number of extra arguments (``*args``)
@@ -576,12 +576,12 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
 
         # Our previous example was:
         @keep_lazy(str)
-        def fancy_utility_function(s, ...):
+        def fancy_utility_function(s, *args, **kwargs):
             ...
 
         # Which can be rewritten as:
         @keep_lazy_text
-        def fancy_utility_function(s, ...):
+        def fancy_utility_function(s, *args, **kwargs):
             ...
 
 ``django.utils.html``