Merge pull request #715 from pganssle/fix-tzwin-docs

Add tzwin documentation

changelog.d/715.doc.rst

@@ -0,0 +1 @@
+Add documentation for the ``dateutil.tz.win`` module and mocked out certain Windows-specific modules so that autodoc can still be run on non-Windows systems. (gh issue #442, pr #715)

dateutil/tz/win.py

@@ -1,3 +1,11 @@
+# -*- coding: utf-8 -*-
+"""
+This module provides an interface to the native time zone data on Windows,
+including :py:class:`datetime.tzinfo` implementations.
+
+Attempting to import this module on a non-Windows platform will raise an
+:py:obj:`ImportError`.
+"""
 # This code was originally contributed by Jeffrey Harris.
 import datetime
 import struct
@@ -39,7 +47,7 @@ def _settzkeyname():
 
 class tzres(object):
     """
-    Class for accessing `tzres.dll`, which contains timezone name related
+    Class for accessing ``tzres.dll``, which contains timezone name related
     resources.
 
     .. versionadded:: 2.5.0
@@ -72,9 +80,10 @@ def load_name(self, offset):
         :param offset:
             A positive integer value referring to a string from the tzres dll.
 
-        ..note:
+        .. note::
+
             Offsets found in the registry are generally of the form
-            `@tzres.dll,-114`. The offset in this case if 114, not -114.
+            ``@tzres.dll,-114``. The offset in this case is 114, not -114.
 
         """
         resource = self.p_wchar()
@@ -146,6 +155,9 @@ def list():
         return result
 
     def display(self):
+        """
+        Return the display name of the time zone.
+        """
         return self._display
 
     def transitions(self, year):
@@ -188,6 +200,17 @@ def _dst_base_offset(self):
 
 
 class tzwin(tzwinbase):
+    """
+    Time zone object created from the zone info in the Windows registry
+
+    These are similar to :py:class:`dateutil.tz.tzrange` objects in that
+    the time zone data is provided in the format of a single offset rule
+    for either 0 or 2 time zone transitions per year.
+
+    :param: name
+        The name of a Windows time zone key, e.g. "Eastern Standard Time".
+        The full list of keys can be retrieved with :func:`tzwin.list`.
+    """
 
     def __init__(self, name):
         self._name = name
@@ -234,6 +257,22 @@ def __reduce__(self):
 
 
 class tzwinlocal(tzwinbase):
+    """
+    Class representing the local time zone information in the Windows registry
+
+    While :class:`dateutil.tz.tzlocal` makes system calls (via the :mod:`time`
+    module) to retrieve time zone information, ``tzwinlocal`` retrieves the
+    rules directly from the Windows registry and creates an object like
+    :class:`dateutil.tz.tzwin`.
+
+    Because Windows does not have an equivalent of :func:`time.tzset`, on
+    Windows, :class:`dateutil.tz.tzlocal` instances will always reflect the
+    time zone settings *at the time that the process was started*, meaning
+    changes to the machine's time zone settings during the run of a program
+    on Windows will **not** be reflected by :class:`dateutil.tz.tzlocal`.
+    Because ``tzwinlocal`` reads the registry directly, it is unaffected by
+    this issue.
+    """
     def __init__(self):
         with winreg.ConnectRegistry(None, winreg.HKEY_LOCAL_MACHINE) as handle:
             with winreg.OpenKey(handle, TZLOCALKEYNAME) as tzlocalkey:

docs/conf.py

@@ -186,6 +186,20 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'dateutildoc'
 
+# -- Options for autodoc -------------------------------------------------
+
+autodoc_mock_imports = ['ctypes.wintypes', 'six.moves.winreg']
+
+# Need to mock this out specifically to avoid errors
+import ctypes
+def pointer_mock(*args, **kwargs):
+    try:
+        return ctypes.POINTER(*args, **kwargs)
+    except Exception:
+        return None
+
+ctypes.POINTER = pointer_mock
+sys.modules['ctypes'] = ctypes
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/index.rst

@@ -24,6 +24,7 @@ Contents:
    relativedelta
    rrule
    tz
+   tz.win <tzwin>
    utils
    zoneinfo
    examples

docs/tz.rst

@@ -36,9 +36,23 @@ Classes
 
 .. autoclass:: tzlocal
 
+.. autoclass:: tzwinlocal
+    :members: display, transitions
+
+    .. note::
+
+        Only available on Windows
+
 .. autoclass:: tzrange
 
 .. autoclass:: tzstr
 
 .. autoclass:: tzical
     :members:
+
+.. autoclass:: tzwin
+    :members: display, transitions, list
+
+    .. note::
+
+        Only available on Windows

docs/tzwin.rst

@@ -0,0 +1,22 @@
+======
+tz.win
+======
+
+.. py:currentmodule:: dateutil.tz.win
+
+.. automodule:: dateutil.tz.win
+
+Classes
+-------
+
+.. autoclass:: tzres
+    :members:
+
+.. autoclass:: tzwin
+    :members: list, display, transitions
+    :undoc-members:
+
+.. autoclass:: tzwinlocal
+    :members: display, transitions
+    :undoc-members:
+