# HG changeset patch
# User Paul Ganssle <paul@ganssle.io>
# Date 1524596281 14400
#      Tue Apr 24 14:58:01 2018 -0400
# Node ID 37e4ff00bb7b62593daec3376e79daed42449542
# Parent  08e04766a1434a7713aec18b017eedd45c5e9f28
Update tzfile examples

diff --git a/changelog.d/671.doc.rst b/changelog.d/671.doc.rst
new file mode 100644
--- /dev/null
+++ b/changelog.d/671.doc.rst
@@ -0,0 +1,1 @@
+Add doctest examples to tzfile documentation. Done by @weatherpattern and @pganssle (gh pr #671)
diff --git a/dateutil/tz/tz.py b/dateutil/tz/tz.py
--- a/dateutil/tz/tz.py
+++ b/dateutil/tz/tz.py
@@ -395,37 +395,54 @@
     <https://www.iana.org/time-zones>`_ with the `zic time zone compiler
     <https://www.freebsd.org/cgi/man.cgi?query=zic&sektion=8>`_
 
+    .. note::
+
+        Only construct a ``tzfile`` directly if you have a specific timezone
+        file on disk that you want to read into a Python ``tzinfo`` object.
+        If you want to get a ``tzfile`` representing a specific IANA zone,
+        (e.g. ``'America/New_York'``), you should call
+        :func:`dateutil.tz.gettz` with the zone identifier.
+
+
     **Examples:**
 
+    Using the US Eastern time zone as an example, we can see that a ``tzfile``
+    provides time zone information for the standard Daylight Saving offsets:
+
+    .. testsetup:: tzfile
+
+        from dateutil.tz import gettz
+        from datetime import datetime
+
     .. doctest:: tzfile
 
-        >>> tz = tzfile("/etc/localtime")
-        >>> datetime.now(tz)
-        datetime.datetime(2003, 9, 27, 12, 3, 48, 392138,
-            tzinfo=tzfile('/etc/localtime'))
+        >>> NYC = gettz('America/New_York')
+        >>> NYC
+        tzfile('/usr/share/zoneinfo/America/New_York')
 
-        >>> datetime.now(tz).astimezone(tzutc())
-        datetime.datetime(2003, 9, 27, 15, 3, 53, 70863, tzinfo=tzutc())
+        >>> print(datetime(2016, 1, 3, tzinfo=NYC))     # EST
+        2016-01-03 00:00:00-05:00
 
-        >>> datetime.now(tz).tzname()
-        'BRST'
-        >>> datetime(2003, 1, 1, tzinfo=tz).tzname()
-        'BRDT'
+        >>> print(datetime(2016, 7, 7, tzinfo=NYC))     # EDT
+        2016-07-07 00:00:00-04:00
 
 
-    Check the daylight limit:
+    The ``tzfile`` structure contains a fully history of the time zone,
+    so historical dates will also have the right offsets. For example, before
+    the adoption of the UTC standards, New York used local solar  mean time:
 
     .. doctest:: tzfile
 
-        >>> tz = tzfile('/usr/share/zoneinfo/EST5EDT')
-        >>> datetime(2003, 4, 6, 1, 59, tzinfo=tz).tzname()
-        'EST'
-        >>> datetime(2003, 4, 6, 2, 00, tzinfo=tz).tzname()
-        'EDT'
-        >>> datetime(2003, 10, 26, 0, 59, tzinfo=tz).tzname()
-        'EDT'
-        >>> datetime(2003, 10, 26, 1, 00, tzinfo=tz).tzname()
-        'EST'
+       >>> print(datetime(1901, 4, 12, tzinfo=NYC))    # LMT
+       1901-04-12 00:00:00-04:56
+
+    And during World War II, New York was on "Eastern War Time", which was a
+    state of permanent daylight saving time:
+
+    .. doctest:: tzfile
+
+        >>> print(datetime(1944, 2, 7, tzinfo=NYC))    # EWT
+        1944-02-07 00:00:00-04:00
 
     """