DOC: fix up docs a bit for datetime64[ns, tz]

Author: jreback

doc/source/timeseries.rst

@@ -1753,22 +1753,45 @@ TZ aware Dtypes
 
 .. versionadded:: 0.17.0
 
-``Series/DatetimeIndex`` with a timezone naive value are represented with a dtype of ``datetime64[ns]``.
+``Series/DatetimeIndex`` with a timezone **naive** value are represented with a dtype of ``datetime64[ns]``.
 
 .. ipython:: python
 
-   dr = pd.date_range('20130101',periods=3)
-   dr
-   s = Series(dr)
-   s
+   dr_naive = pd.date_range('20130101',periods=3)
+   dr_naive
+   s_naive = Series(dr_naive)
+   s_naive
 
-``Series/DatetimeIndex`` with a timezone aware value are represented with a dtype of ``datetime64[ns, tz]``.
+``Series/DatetimeIndex`` with a timezone **aware** value are represented with a dtype of ``datetime64[ns, tz]``.
 
 .. ipython:: python
 
-   dr = pd.date_range('20130101',periods=3,tz='US/Eastern')
-   dr
-   s = Series(dr)
-   s
+   dr_aware = pd.date_range('20130101',periods=3,tz='US/Eastern')
+   dr_aware
+   s_aware = Series(dr_aware)
+   s_aware
+
+Both of these ``Series`` can be manipulated via the ``.dt`` accessor, see :ref:`here <basics.dt_accessors>`.
+See the :ref:`docs <timeseries.dtypes>` for more details.
+
+.. note::
+
+   Using the ``.values`` accessor on a ``Series``, returns an numpy array of the data.
+   These values are converted to UTC, as numpy does not currently support timezones (even though it is *printing* in the local timezone!).
+
+   .. ipython:: python
+
+      s_naive.values
+      s_aware.values
+
+   Further note that once converted to a numpy array these would lose the tz tenor.
+
+   .. ipython:: python
+
+      Series(s_aware.values)
+
+   However, these can be easily converted
+
+   .. ipython:: python
 
-Both of these ``Series`` can be manipulated via the ``.dt`` accessor, see the :ref:`docs <basics.dt_accessors>` as well.
+      Series(s_aware).dt.tz_localize('UTC').dt.tz_convert('US/Eastern')

doc/source/whatsnew/v0.17.0.txt

@@ -447,9 +447,9 @@ Datetime with TZ
 
 We are adding an implementation that natively supports datetime with timezones. A ``Series`` or a ``DataFrame`` column previously
 *could* be assigned a datetime with timezones, and would work as an ``object`` dtype. This had performance issues with a large
-number rows. (:issue:`8260`, :issue:`10763`)
+number rows. See the :ref:`docs <timeseries.timezone_series>` for more details. (:issue:`8260`, :issue:`10763`).
 
-The new implementation allows for having a single-timezone across all rows, and operating on it in a performant manner.
+The new implementation allows for having a single-timezone across all rows, with operations in a performant manner.
 
 .. ipython:: python
 
@@ -469,13 +469,15 @@ This uses a new-dtype representation as well, that is very similar in look-and-f
 .. ipython:: python
 
    df['B'].dtype
-   type(df['B']).dtype
+   type(df['B'].dtype)
 
 .. note::
 
    There is a slightly different string repr for the underlying ``DatetimeIndex`` as a result of the dtype changes, but
    functionally these are the same.
 
+   Previous Behavior:
+
    .. code-block:: python
 
       In [1]: pd.date_range('20130101',periods=3,tz='US/Eastern')
@@ -486,12 +488,13 @@ This uses a new-dtype representation as well, that is very similar in look-and-f
       In [2]: pd.date_range('20130101',periods=3,tz='US/Eastern').dtype
       Out[2]: dtype('<M8[ns]')
 
+   New Behavior:
+
    .. ipython:: python
 
       pd.date_range('20130101',periods=3,tz='US/Eastern')
       pd.date_range('20130101',periods=3,tz='US/Eastern').dtype
 
-
 .. _whatsnew_0170.api_breaking.convert_objects:
 
 Changes to convert_objects