Merged initial Sphinx documentation structure.

There's still a long way to go in this direction, but the basic
framework is now in place.  Toss in numpydoc-style docstrings 
  http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
when you have time, and things will gradually improve over time.

I also punted our user ID creation/parsing in libbe.ui.util.user to
the email module.  This way IDs are handled in an RFC-compliant way
(less suprising for users) and by someone else (less work for us :).

1 files changed, 33 insertions, 18 deletions

diff --git a/libbe/storage/util/properties.py b/libbe/storage/util/properties.py
index 55bac85..b5681b1 100644
--- a/libbe/storage/util/properties.py
+++ b/libbe/storage/util/properties.py
@@ -16,16 +16,24 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
-"""
-This module provides a series of useful decorators for defining
-various types of properties.  For example usage, consider the
-unittests at the end of the module.
-
-See
-  http://www.python.org/dev/peps/pep-0318/
-and
-  http://www.phyast.pitt.edu/~micheles/python/documentation.html
-for more information on decorators.
+"""Provides a series of useful decorators for defining various types
+of properties.
+
+For example usage, consider the unittests at the end of the module.
+
+Notes
+-----
+
+See `PEP 318` and Michele Simionato's `decorator documentation` for
+more information on decorators.
+
+.. _PEP 318: http://www.python.org/dev/peps/pep-0318/
+.. _decorator documentation: http://www.phyast.pitt.edu/~micheles/python/documentation.html
+
+See Also
+--------
+:mod:`libbe.storage.util.settings_object` : bundle properties into a convenient package
+
 """
 
 import copy
@@ -336,12 +344,11 @@ def primed_property(primer, initVal=None, unprimeableVal=None):
     return decorator
 
 def change_hook_property(hook, mutable=False, default=None):
-    """
-    Call the function hook(instance, old_value, new_value) whenever a
-    value different from the current value is set (instance is a a
-    reference to the class instance to which this property belongs).
+    """Call the function `hook` whenever a value different from the
+    current value is set.
+
     This is useful for saving changes to disk, etc.  This function is
-    called _after_ the new value has been stored, allowing you to
+    called *after* the new value has been stored, allowing you to
     change the stored value if you want.
 
     In the case of mutables, things are slightly trickier.  Because
@@ -350,11 +357,19 @@ def change_hook_property(hook, mutable=False, default=None):
     mutable value, and checking for changes whenever the property is
     set (obviously) or retrieved (to check for external changes).  So
     long as you're conscientious about accessing the property after
-    making external modifications, mutability won't be a problem.
+    making external modifications, mutability won't be a problem::
+
       t.x.append(5) # external modification
       t.x           # dummy access notices change and triggers hook
-    See testChangeHookMutableProperty for an example of the expected
-    behavior.
+
+    See :class:`testChangeHookMutableProperty` for an example of the
+    expected behavior.
+
+    Parameters
+    ----------
+    hook : fn
+      `hook(instance, old_value, new_value)`, where `instance` is a
+      reference to the class instance to which this property belongs.
     """
     def decorator(funcs):
         if hasattr(funcs, "__call__"):