[3.0.x] Fixed #27921 -- Clarified usage of make_aware() with is_dst argument.

Backport of c2678e49759e5c4c329bff0eeca2886267005d21 from master

1 files changed, 8 insertions, 5 deletions

diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 1a0c36dc43..117ed2f4d8 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -972,11 +972,14 @@ appropriate entities.
     post-transition respectively.
 
     The ``pytz.NonExistentTimeError`` exception is raised if you try to make
-    ``value`` aware during a DST transition such that the time never occurred
-    (when entering into DST). Setting ``is_dst`` to ``True`` or ``False`` will
-    avoid the exception by moving the hour backwards or forwards by 1
-    respectively. For example, ``is_dst=True`` would change a nonexistent
-    time of 2:30 to 1:30 and ``is_dst=False`` would change the time to 3:30.
+    ``value`` aware during a DST transition such that the time never occurred.
+    For example, if the 2:00 hour is skipped during a DST transition, trying to
+    make 2:30 aware in that time zone will raise an exception. To avoid that
+    you can use ``is_dst`` to specify how ``make_aware()`` should interpret
+    such a nonexistent time. If ``is_dst=True`` then the above time would be
+    interpreted as 2:30 DST time (equivalent to 1:30 local time). Conversely,
+    if ``is_dst=False`` the time would be interpreted as 2:30 standard time
+    (equivalent to 3:30 local time).
 
 .. function:: make_naive(value, timezone=None)