add more docs

11 files changed, 124 insertions, 38 deletions

diff --git a/dateutil/easter.py b/dateutil/easter.py
index 0c119ce..00fad99 100644
--- a/dateutil/easter.py
+++ b/dateutil/easter.py
@@ -1,4 +1,8 @@
 # -*- coding: utf-8 -*-
+"""
+This module offers a generic easter computing method for any given year, using
+Western, Orthodox or Julian algorithms.
+"""
 
 import datetime
 
@@ -18,7 +22,7 @@ def easter(year, method=EASTER_WESTERN):
 
     This algorithm implements three different easter
     calculation methods:
-    
+
     1 - Original calculation in Julian calendar, valid in
         dates after 326 AD
     2 - Original method, with date converted to Gregorian
@@ -33,7 +37,7 @@ def easter(year, method=EASTER_WESTERN):
     EASTER_WESTERN  = 3
 
     The default method is method 3.
-    
+
     More about the algorithm may be found at:
 
     http://users.chariot.net.au/~gmarts/eastalg.htm
diff --git a/dateutil/parser.py b/dateutil/parser.py
index 3839635..ade34b9 100644
--- a/dateutil/parser.py
+++ b/dateutil/parser.py
@@ -1,4 +1,8 @@
 # -*- coding:iso-8859-1 -*-
+"""
+This module offers a generic date/time string parser which is able to parse
+most known formats to represent a date and/or time.
+"""
 from __future__ import unicode_literals
 
 import datetime
diff --git a/dateutil/relativedelta.py b/dateutil/relativedelta.py
index e1d8ee6..213ec0b 100644
--- a/dateutil/relativedelta.py
+++ b/dateutil/relativedelta.py
@@ -1,5 +1,4 @@
 # -*- coding: utf-8 -*-
-
 import datetime
 import calendar
 
@@ -40,16 +39,17 @@ MO, TU, WE, TH, FR, SA, SU = weekdays = tuple([weekday(x) for x in range(7)])
 class relativedelta(object):
     """
 The relativedelta type is based on the specification of the excelent
-work done by M.-A. Lemburg in his mx.DateTime extension. However,
+work done by M.-A. Lemburg in his
+`mx.DateTime <http://www.egenix.com/files/python/mxDateTime.html>`_ extension. However,
 notice that this type does *NOT* implement the same algorithm as
 his work. Do *NOT* expect it to behave like mx.DateTime's counterpart.
 
 There's two different ways to build a relativedelta instance. The
-first one is passing it two date/datetime classes:
+first one is passing it two date/datetime classes::
 
     relativedelta(datetime1, datetime2)
 
-And the other way is to use the following keyword arguments:
+And the other way is to use the following keyword arguments::
 
     year, month, day, hour, minute, second, microsecond:
         Absolute information.
@@ -74,26 +74,26 @@ And the other way is to use the following keyword arguments:
 
 Here is the behavior of operations with relativedelta:
 
-1) Calculate the absolute year, using the 'year' argument, or the
+1. Calculate the absolute year, using the 'year' argument, or the
    original datetime year, if the argument is not present.
 
-2) Add the relative 'years' argument to the absolute year.
+2. Add the relative 'years' argument to the absolute year.
 
-3) Do steps 1 and 2 for month/months.
+3. Do steps 1 and 2 for month/months.
 
-4) Calculate the absolute day, using the 'day' argument, or the
+4. Calculate the absolute day, using the 'day' argument, or the
    original datetime day, if the argument is not present. Then,
    subtract from the day until it fits in the year and month
    found after their operations.
 
-5) Add the relative 'days' argument to the absolute day. Notice
+5. Add the relative 'days' argument to the absolute day. Notice
    that the 'weeks' argument is multiplied by 7 and added to
    'days'.
 
-6) Do steps 1 and 2 for hour/hours, minute/minutes, second/seconds,
+6. Do steps 1 and 2 for hour/hours, minute/minutes, second/seconds,
    microsecond/microseconds.
 
-7) If the 'weekday' argument is present, calculate the weekday,
+7. If the 'weekday' argument is present, calculate the weekday,
    with the given (wday, nth) tuple. wday is the index of the
    weekday (0-6, 0=Mon), and nth is the number of weeks to add
    forward or backward, depending on its signal. Notice that if
diff --git a/dateutil/rrule.py b/dateutil/rrule.py
index 5d9eb0c..91bdedf 100644
--- a/dateutil/rrule.py
+++ b/dateutil/rrule.py
@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
-
+"""
+The rrule module offers a small, complete, and very fast, implementation of
+the recurrence rules documented in the
+`iCalendar RFC <http://www.ietf.org/rfc/rfc2445.txt>`_,
+including support for caching of results.
+"""
 import itertools
 import datetime
 import calendar
@@ -157,11 +162,13 @@ class rrulebase(object):
 
     # __len__() introduces a large performance penality.
     def count(self):
+        """ Returns the number of recurrences in this set. It will have go trough the whole recurrence, if this hasn't been done before. """
         if self._len is None:
             for x in self: pass
         return self._len
 
     def before(self, dt, inc=False):
+        """ Returns the last recurrence before the given datetime instance. The inc keyword defines what happens if dt is an occurrence. With inc == True, if dt itself is an occurrence, it will be returned. """
         if self._cache_complete:
             gen = self._cache
         else:
@@ -180,6 +187,7 @@ class rrulebase(object):
         return last
 
     def after(self, dt, inc=False):
+        """ Returns the first recurrence after the given datetime instance. The inc keyword defines what happens if dt is an occurrence. With inc == True, if dt itself is an occurrence, it will be returned.  """
         if self._cache_complete:
             gen = self._cache
         else:
@@ -195,6 +203,7 @@ class rrulebase(object):
         return None
 
     def between(self, after, before, inc=False):
+        """ Returns all the occurrences of the rrule between after and before. The inc keyword defines what happens if after and/or before are themselves occurrences. With inc == True, they will be included in the list, if they are found in the recurrence set. """
         if self._cache_complete:
             gen = self._cache
         else:
@@ -224,7 +233,57 @@ class rrulebase(object):
         return l
 
 class rrule(rrulebase):
-    """  The basic rrule class """
+    """
+    That's the base of the rrule operation. It accepts all the keywords
+    defined in the RFC as its constructor parameters (except byday,
+    which was renamed to byweekday) and more. The constructor prototype is::
+
+            rrule(freq)
+
+    Where freq must be one of YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY, or SECONDLY.
+
+    Additionally, it supports the following keyword arguments:
+
+    :param cache:
+        If given, it must be a boolean value specifying to enable or disable caching of results. If you will use the same
+        rrule instance multiple times, enabling caching will improve the performance considerably.
+    :param dtstart:
+        The recurrence start. Besides being the base for the recurrence, missing parameters in the final recurrence instances will also be extracted from this date. If not
+        given, datetime.now() will be used instead.
+    :param interval:
+        The interval between each freq iteration. For example, when using YEARLY, an interval of 2 means once every two years, but with HOURLY, it means once every two hours. The default interval is 1.
+    :param wkst:
+        The week start day. Must be one of the MO, TU, WE constants, or an integer, specifying the first day of the week. This will affect recurrences based on weekly periods. The default week start is got from calendar.firstweekday(), and may be modified by calendar.setfirstweekday().
+    :param count:
+        How many occurrences will be generated.
+    :param until:
+        If given, this must be a datetime instance, that will specify the limit of the recurrence. If a recurrence instance happens to be the same as the datetime instance given in the until keyword, this will be the last occurrence.
+    :param bysetpos:
+        If given, it must be either an integer, or a sequence of integers, positive or negative. Each given integer will specify an occurrence number, corresponding to the nth occurrence of the rule inside the frequency period. For
+        example, a bysetpos of -1 if combined with a MONTHLY frequency, and a byweekday of (MO, TU, WE, TH, FR), will result in the last work day of every month.
+    :param bymonth:
+        If given, it must be either an integer, or a sequence of integers, meaning the months to apply the recurrence to.
+    :param bymonthday:
+        If given, it must be either an integer, or a sequence of integers, meaning the month days to apply the recurrence to.
+    :param byyearday:
+        If given, it must be either an integer, or a sequence of integers, meaning the year days to apply the recurrence to.
+    :param byweekno:
+        If given, it must be either an integer, or a sequence of integers, meaning the week numbers to apply the recurrence to. Week numbers have the meaning described in ISO8601, that is, the first week of the year is that containing at least four days of the new year.
+    :param byweekday:
+        If given, it must be either an integer (0 == MO), a sequence of integers, one of the weekday constants (MO, TU, etc), or a sequence of these constants. When given, these variables will define the weekdays where the recurrence will be applied. It's also possible to use an argument n for the weekday instances, which will mean the nth occurrence of this weekday in the period. For example, with MONTHLY, or with YEARLY and BYMONTH, using FR(+1) in byweekday will specify the first friday of the month where the recurrence happens. Notice that in the RFC documentation, this is specified as BYDAY, but was renamed to avoid the ambiguity of that keyword.
+    :param byhour:
+        If given, it must be either an integer, or a sequence of integers, meaning the hours to apply the recurrence to.
+    :param byminute:
+        If given, it must be either an integer, or a sequence of integers, meaning the minutes to apply the recurrence to.
+    :param bysecond:
+        If given, it must be either an integer, or a sequence of integers, meaning the seconds to apply the recurrence to.
+    :param byeaster:
+        If given, it must be either an integer, or a sequence of integers, positive or negative. Each integer will define an offset from the Easter Sunday. Passing the offset
+
+        0 to byeaster will yield the Easter Sunday itself. This is an extension to the RFC specification.
+
+
+     """
     def __init__(self, freq, dtstart=None,
                  interval=1, wkst=None, count=None, until=None, bysetpos=None,
                  bymonth=None, bymonthday=None, byyearday=None, byeaster=None,
@@ -426,7 +485,7 @@ class rrule(rrulebase):
                      HOURLY:ii.ddayset,
                      MINUTELY:ii.ddayset,
                      SECONDLY:ii.ddayset}[freq]
-        
+
         if freq < HOURLY:
             timeset = self._timeset
         else:
@@ -821,6 +880,12 @@ class _iterinfo(object):
 
 
 class rruleset(rrulebase):
+    """ The rruleset type allows more complex recurrence setups, mixing
+    multiple rules, dates, exclusion rules, and exclusion dates. The type
+    constructor takes the following keyword arguments:
+
+    :param cache: If True, caching of results will be enabled, improving
+                  performance of multiple queries considerably. """
 
     class _genitem(object):
         def __init__(self, genlist, gen):
@@ -860,15 +925,21 @@ class rruleset(rrulebase):
         self._exdate = []
 
     def rrule(self, rrule):
+        """ Include the given :py:`rrule` instance in the recurrence set generation. """
         self._rrule.append(rrule)
 
     def rdate(self, rdate):
+        """ Include the given :py:`datetime` instance in the recurrence set generation. """
         self._rdate.append(rdate)
 
     def exrule(self, exrule):
+        """ Include the given rrule instance in the recurrence set
+        exclusion list. Dates which are part of the given recurrence
+        rules will not be generated, even if some inclusive rrule or rdate matches them."""
         self._exrule.append(exrule)
 
     def exdate(self, exdate):
+        """ Include the given datetime instance in the recurrence set exclusion list. Dates included that way will not be generated, even if some inclusive rrule or rdate matches them. """
         self._exdate.append(exdate)
 
     def _iter(self):
diff --git a/dateutil/tz.py b/dateutil/tz.py
index 10a74fa..8b07844 100644
--- a/dateutil/tz.py
+++ b/dateutil/tz.py
@@ -1,5 +1,12 @@
 # -*- coding: utf-8 -*-
-
+"""
+This module offers timezone implementations subclassing the abstract
+:py:`datetime.tzinfo` type. There are classes to handle tzfile format files
+(usually are in :file:`/etc/localtime`, :file:`/usr/share/zoneinfo`, etc), TZ
+environment string (in all known formats), given ranges (with help from
+relative deltas), local machine timezone, fixed offset timezone, and UTC
+timezone.
+"""
 import datetime
 import platform
 import struct
@@ -42,7 +49,7 @@ class tzutc(datetime.tzinfo):
 
     def utcoffset(self, dt):
         return ZERO
-     
+
     def dst(self, dt):
         return ZERO
 
@@ -119,7 +126,7 @@ class tzlocal(datetime.tzinfo):
     def _isdst(self, dt):
         # We can't use mktime here. It is unstable when deciding if
         # the hour near to a change is DST or not.
-        # 
+        #
         # timestamp = time.mktime((dt.year, dt.month, dt.day, dt.hour,
         #                         dt.minute, dt.second, dt.weekday(), 0, -1))
         # return time.localtime(timestamp).tm_isdst
@@ -205,7 +212,7 @@ class tzfile(datetime.tzinfo):
 
     # http://www.twinsun.com/tz/tz-link.htm
     # ftp://ftp.iana.org/tz/tz*.tar.gz
-    
+
     def __init__(self, fileobj, filename=None):
         file_opened_here = False
         if isinstance(fileobj, string_types):
@@ -467,7 +474,7 @@ class tzfile(datetime.tzinfo):
         # However, this class stores historical changes in the
         # dst offset, so I belive that this wouldn't be the right
         # way to implement this.
-        
+
     @tzname_in_python2
     def tzname(self, dt):
         if not self._ttinfo_std:
@@ -574,7 +581,7 @@ class tzrange(datetime.tzinfo):
     __reduce__ = object.__reduce__
 
 class tzstr(tzrange):
-    
+
     def __init__(self, s):
         global parser
         if not parser:
diff --git a/dateutil/tzwin.py b/dateutil/tzwin.py
index f0773f2..c02cd3e 100644
--- a/dateutil/tzwin.py
+++ b/dateutil/tzwin.py
@@ -41,7 +41,7 @@ class tzwinbase(datetime.tzinfo):
             return datetime.timedelta(minutes=minutes)
         else:
             return datetime.timedelta(0)
-        
+
     def tzname(self, dt):
         if self._isdst(dt):
             return self._dstname
@@ -61,7 +61,7 @@ class tzwinbase(datetime.tzinfo):
 
     def display(self):
         return self._display
-    
+
     def _isdst(self, dt):
         dston = picknthweekday(dt.year, self._dstmonth, self._dstdayofweek,
                                self._dsthour, self._dstminute,
@@ -90,12 +90,12 @@ class tzwin(tzwinbase):
         self._dstname = keydict["Dlt"].encode("iso-8859-1")
 
         self._display = keydict["Display"]
-        
+
         # See http://ww_winreg.jsiinc.com/SUBA/tip0300/rh0398.htm
         tup = struct.unpack("=3l16h", keydict["TZI"])
         self._stdoffset = -tup[0]-tup[1]         # Bias + StandardBias * -1
         self._dstoffset = self._stdoffset-tup[2] # + DaylightBias * -1
-        
+
         (self._stdmonth,
          self._stddayofweek,  # Sunday = 0
          self._stdweeknumber, # Last = 5
@@ -116,7 +116,7 @@ class tzwin(tzwinbase):
 
 
 class tzwinlocal(tzwinbase):
-    
+
     def __init__(self):
 
         handle = winreg.ConnectRegistry(None, winreg.HKEY_LOCAL_MACHINE)
@@ -137,7 +137,7 @@ class tzwinlocal(tzwinbase):
             self._display = None
 
         handle.Close()
-        
+
         self._stdoffset = -keydict["Bias"]-keydict["StandardBias"]
         self._dstoffset = self._stdoffset-keydict["DaylightBias"]
 
diff --git a/docs/easter.rst b/docs/easter.rst
index 1570ae1..13b5903 100644
--- a/docs/easter.rst
+++ b/docs/easter.rst
@@ -1,6 +1,6 @@
-=====
+======
 easter
-=====
+======
 .. automodule:: dateutil.easter
    :members:
    :undoc-members:
diff --git a/docs/parser.rst b/docs/parser.rst
index 936fdf8..c579974 100644
--- a/docs/parser.rst
+++ b/docs/parser.rst
@@ -1,6 +1,6 @@
-=====
+======
 parser
-=====
+======
 .. automodule:: dateutil.parser
    :members:
    :undoc-members:
diff --git a/docs/relativedelta.rst b/docs/relativedelta.rst
index 3db8d58..23c52c7 100644
--- a/docs/relativedelta.rst
+++ b/docs/relativedelta.rst
@@ -1,6 +1,6 @@
-=====
+=============
 relativedelta
-=====
+=============
 .. automodule:: dateutil.relativedelta
    :members:
    :undoc-members:
diff --git a/docs/tz.rst b/docs/tz.rst
index f0f2b21..5fd5bf5 100644
--- a/docs/tz.rst
+++ b/docs/tz.rst
@@ -1,6 +1,6 @@
-=====
+==
 tz
-=====
+==
 .. automodule:: dateutil.tz
    :members:
    :undoc-members:
diff --git a/docs/zoneinfo.rst b/docs/zoneinfo.rst
index 097e1a4..77c1eb2 100644
--- a/docs/zoneinfo.rst
+++ b/docs/zoneinfo.rst
@@ -1,6 +1,6 @@
-=====
+========
 zoneinfo
-=====
+========
 .. automodule:: dateutil.zoneinfo
    :members:
    :undoc-members: