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, 22 insertions, 35 deletions

diff --git a/libbe/bugdir.py b/libbe/bugdir.py
index 3c3afa0..65136fe 100644
--- a/libbe/bugdir.py
+++ b/libbe/bugdir.py
@@ -19,8 +19,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
-"""
-Define the BugDir class for representing bug comments.
+"""Define the :class:`BugDir` class for storing a collection of bugs.
 """
 
 import copy
@@ -49,31 +48,6 @@ if libbe.TESTING == True:
     import libbe.storage.base
 
 
-class NoBugDir(Exception):
-    def __init__(self, path):
-        msg = "The directory \"%s\" has no bug directory." % path
-        Exception.__init__(self, msg)
-        self.path = path
-
-class NoRootEntry(Exception):
-    def __init__(self, path):
-        self.path = path
-        Exception.__init__(self, "Specified root does not exist: %s" % path)
-
-class AlreadyInitialized(Exception):
-    def __init__(self, path):
-        self.path = path
-        Exception.__init__(self,
-                           "Specified root is already initialized: %s" % path)
-
-class MultipleBugMatches(ValueError):
-    def __init__(self, shortname, matches):
-        msg = ("More than one bug matches %s.  "
-               "Please be more specific.\n%s" % (shortname, matches))
-        ValueError.__init__(self, msg)
-        self.shortname = shortname
-        self.matches = matches
-
 class NoBugMatches(libbe.util.id.NoIDMatches):
     def __init__(self, *args, **kwargs):
         libbe.util.id.NoIDMatches.__init__(self, *args, **kwargs)
@@ -82,15 +56,27 @@ class NoBugMatches(libbe.util.id.NoIDMatches):
             return 'No bug matches %s' % self.id
         return self.msg
 
-class DiskAccessRequired (Exception):
-    def __init__(self, goal):
-        msg = "Cannot %s without accessing the disk" % goal
-        Exception.__init__(self, msg)
-
 
 class BugDir (list, settings_object.SavedSettingsObject):
-    """
-    TODO: simple bugdir manipulation examples...
+    """A BugDir is a container for :class:`~libbe.bug.Bug`\s, with some
+    additional attributes.
+
+    Parameters
+    ----------
+    storage : :class:`~libbe.storage.base.Storage`
+       Storage instance containing the bug directory.  If
+       `from_storage` is `False`, `storage` may be `None`.
+    uuid : str, optional
+       Set the bugdir UUID (see :mod:`libbe.util.id`).
+       Useful if you are loading one of several bugdirs
+       stored in a single Storage instance.
+    from_storage : bool, optional
+       If `True`, attempt to load from storage.  Otherwise,
+       setup in memory, saving to `storage` if it is not `None`.
+
+    See Also
+    --------
+    :class:`SimpleBugDir` for some bugdir manipulation exampes.
     """
 
     settings_properties = []
@@ -344,7 +330,8 @@ class RevisionedBugDir (BugDir):
 if libbe.TESTING == True:
     class SimpleBugDir (BugDir):
         """
-        For testing.  Set memory=True for a memory-only bugdir.
+        For testing.  Set ``memory=True`` for a memory-only bugdir.
+
         >>> bugdir = SimpleBugDir()
         >>> uuids = list(bugdir.uuids())
         >>> uuids.sort()