Doc fixes, plus Tree now has discover method.

docs/Tags-Categories.rst

@@ -31,16 +31,16 @@ analysis code. For example, if we have Treants with different shades of bark
 (say, "dark" and "light"), we can make a category that reflects this. In this
 case, we categorize ``sprout`` as "dark" ::
     
-    >>> s.categories['roots'] = 'dark'
+    >>> s.categories['bark'] = 'dark'
     >>> s.categories
-    <Categories({'roots': 'shallow'})>
+    <Categories({'bark': 'dark'})>
 
 Perhaps we've written some analysis code that will take both "dark" and "light"
 Treants as input but needs to handle them differently. It can see what variety
 of **Treant** it is working with using ::
 
-    >>> s.categories['roots']
-    'shallow'
+    >>> s.categories['bark']
+    'dark'
 
 The keys for categories must be strings, but the values may be strings, numbers
 (floats, ints), or booleans (``True``, ``False``). ``None`` may not be used since

docs/Trees.rst

@@ -46,13 +46,13 @@ Paths that resolve as being inside a Tree give `True` for membership tests ::
     >>> t['a/file'] in t
     True
 
-Note that neither of these items need exist ::
+Note that these items need not exist ::
 
     >>> t['a/file'].exists
     False
 
 in which case whether a Tree or Leaf is returned is dependent on an ending
-``/``. We can create directories and empty files easily enough, though ::
+``/``. We can create directories and empty files easily enough, though::
 
     >>> adir = t['a/directory/'].make()
     >>> adir.exists

src/datreant/core/manipulators.py

@@ -14,8 +14,9 @@ def discover(dirpath='.', depth=None, treantdepth=None):
 
     Parameters
     ----------
-    dirpath : string
-        Directory within which to search for Treants.
+    dirpath : string, Tree
+        Directory within which to search for Treants. May also be an existing
+        Tree.
     depth : int
         Maximum directory depth to tolerate while traversing in search of
         Treants. ``None`` indicates no depth limit.
@@ -30,6 +31,14 @@ def discover(dirpath='.', depth=None, treantdepth=None):
 
     """
     from .collections import Bundle
+    from .trees import Tree
+
+    if isinstance(dirpath, Tree):
+        if not dirpath.exists:
+            raise OSError("Tree doesn't exist in the filesystem")
+
+        dirpath = dirpath.abspath
+
     found = list()
 
     startdepth = len(dirpath.split(os.sep))

src/datreant/core/trees.py

@@ -12,6 +12,7 @@
 from asciitree import LeftAligned
 
 from .util import makedirs
+from .manipulators import discover
 from . import _TREELIMBS
 
 
@@ -358,6 +359,8 @@ def children(self):
         from .collections import View
         return View(self.trees + self.leaves + self.hidden)
 
+    discover = discover
+
     @property
     def treants(self):
         """Bundle of all Treants found within this Tree.