Lots of doc updates; moved API references to own section.

The autodoc API references can get pretty overwhelming, so moved to
their own main section of the docs. We link to them in each part of the
user documentation as it already exists.

Removed Bundle.discover. It really just looked like a point of
confusion, and is unnecessary since discover is now a top-level function
in the library.

docs/api.rst

@@ -0,0 +1,11 @@
+=============
+API Reference
+=============
+This is an overview of the ``datreant.core`` API.
+
+
+.. toctree::
+
+    api_treants.rst
+    api_filesystem.rst
+    api_bundle.rst

docs/api_bundle.rst

@@ -0,0 +1,46 @@
+Treant aggregation
+==================
+These are the API components of ``datreant.core`` for working with multiple
+Treants at once, and treating them in aggregate.
+
+.. _Bundle_api:
+
+Bundle
+------
+The class :class:`datreant.core.Bundle` functions as an ordered set of
+Treants. It allows common operations on Treants to be performed in aggregate,
+but also includes mechanisms for filtering and grouping based on Treant
+attributes, such as tags and categories.
+
+
+Bundles can be created from all Treants found in a directory tree with
+:func:`datreant.core.discover`:
+
+.. autofunction:: datreant.core.discover
+
+They can also be created directly from any number of Treants:
+
+.. autoclass:: datreant.core.Bundle
+    :members:
+    :inherited-members:
+    :noindex:
+
+AggTags
+```````
+The class :class:`datreant.core.agglimbs.AggTags` is the interface used by
+Bundles to access their members' tags.
+
+.. autoclass:: datreant.core.agglimbs.AggTags
+    :members:
+    :inherited-members:
+    :noindex:
+
+AggCategories
+`````````````
+The class :class:`datreant.core.agglimbs.AggCategories` is the interface used
+by Bundles to access their members' categories.
+
+.. autoclass:: datreant.core.agglimbs.AggCategories
+    :members:
+    :inherited-members:
+    :noindex:

docs/api_filesystem.rst

@@ -0,0 +1,41 @@
+Filesystem manipulation
+=======================
+The components of ``datreant.core`` documented here are those designed for
+working directly with filesystem objects, namely directories and files.
+
+.. _Tree_api:
+
+Tree
+----
+The class :class:`datreant.core.Tree` is an interface to a directory in the
+filesystem.
+
+.. autoclass:: datreant.core.Tree
+    :members:
+    :inherited-members:
+    :noindex:
+
+.. _Leaf_api:
+
+Leaf
+----
+The class :class:`datreant.core.Leaf` is an interface to a file in the
+filesystem.
+
+.. autoclass:: datreant.core.Leaf
+    :members:
+    :inherited-members:
+    :noindex:
+
+.. _View_api:
+
+View
+----
+The class :class:`datreant.core.View` is an ordered set of Trees and Leaves.
+It allows for convenient operations on its members as a collective, as well
+as providing mechanisms for filtering and subselection.
+
+.. autoclass:: datreant.core.View
+    :members:
+    :inherited-members:
+    :noindex:

docs/api_treants.rst

@@ -0,0 +1,63 @@
+Treants
+=======
+Treants are the core units of functionality of ``datreant``. They function as
+specially marked directories with distinguishing characteristics. They designed
+to be subclassed, with their functionality extendable with attachable Limbs.
+
+The components documented here are those included within ``datreant.core``.
+
+.. _Treant_api:
+
+Treant
+------
+The class :class:`datreant.core.Treant` is the central object of ``datreant.core``. 
+
+.. autoclass:: datreant.core.Treant
+    :members:
+    :inherited-members:
+    :noindex:
+
+.. _Tags_api:
+
+Tags
+````
+The class :class:`datreant.core.limbs.Tags` is the interface used by Treants to
+access their tags. 
+
+.. autoclass:: datreant.core.limbs.Tags
+    :members:
+    :inherited-members:
+    :noindex:
+
+.. _Categories_api:
+
+Categories
+``````````
+The class :class:`datreant.core.limbs.Categories` is the interface used by
+Treants to access their categories.
+
+.. autoclass:: datreant.core.limbs.Categories
+    :members:
+    :inherited-members:
+    :noindex:
+
+.. _Group_api:
+
+Group
+-----
+The class :class:`datreant.core.Group` is a Treant with the ability to store
+member locations as a persistent Bundle within its state file. 
+
+.. autoclass:: datreant.core.Group
+    :members:
+    :inherited-members:
+    :noindex:
+
+Members
+```````
+The class :class:`datreant.core.limbs.MemberBundle` is the interface used
+by a Group to manage its members. 
+
+.. autoclass:: datreant.core.limbs.MemberBundle
+    :members:
+    :inherited-members:

docs/Bundles.rst → docs/bundles.rst

@@ -41,10 +41,9 @@ For this simple example all our Treants were in this directory, so it's not
 quite as useful. But for a directory structure that is deep and convoluted perhaps
 from a project spanning years, ``discover`` lets you get a Bundle of all Treants
 in the tree with little effort. You can then filter on tags and categories to
-get Bundles of the Treants you actually want to work with (see below).
-
-.. autofunction:: datreant.core.discover
+get Bundles of the Treants you actually want to work with.
 
+See the :func:`datreant.core.discover` API reference for more details.
 
 Basic member selection
 ======================
@@ -173,20 +172,6 @@ Fuzzy matching for tags
 Grouping with Treant categories
 ===============================
 
-Reference: Bundle
-=================
-.. autoclass:: datreant.core.Bundle
-    :members:
-    :inherited-members:
-
-Reference: AggTags
-==================
-.. autoclass:: datreant.core.agglimbs.AggTags
-    :members:
-    :inherited-members:
-
-Reference: AggCategories
-========================
-.. autoclass:: datreant.core.agglimbs.AggCategories
-    :members:
-    :inherited-members:
+API Reference: Bundle
+=====================
+See the :ref:`Bundle_api` API reference for more details.

docs/Groups.rst → docs/groups.rst

@@ -65,17 +65,6 @@ the same stored information at all times ::
     >>> g2.tags
     <Tags(['oaks'])>
 
-Reference: Group
-================
-.. autoclass:: datreant.core.Group
-    :members:
-    :inherited-members:
-
-Reference: Members
-==================
-The class :class:`datreant.core.limbs.MemberBundle` is the interface used
-by a Group to manage its members. 
-
-.. autoclass:: datreant.core.limbs.MemberBundle
-    :members:
-    :inherited-members:
+API Reference: Group
+====================
+See the :ref:`Group_api` API reference for more details.

docs/index.rst

@@ -69,47 +69,30 @@ Contributing
 This project is still under heavy development, and there are certainly rough
 edges and bugs. Issues and pull requests welcome! 
 
-.. raw:: html
-
-    <div style="display:none">
-
 --------------------------------------------------------------------------------
 
-Documentation
--------------
-
 .. toctree::
     :maxdepth: 1
+    :caption: User Documentation
 
     install
-    Treants
-    Tags-Categories
-    Trees
-    Views
-    Bundles
-    Groups
-    API
-
-
-For Developers
---------------
-.. toctree::
-    :maxdepth: 1
-
-    Limbs-TreeLimbs
-    AggLimbs-AggTreeLimbs
+    treants
+    tags-categories
+    trees
+    views
+    bundles
+    groups
+    api 
 
+.. .. toctree::
+..     :maxdepth: 1
+    :caption: For Developers
+    limbs-treelimbs
+    agglimbs-aggtreelimbs
 
-Miscellaneous
--------------
 
 .. toctree::
     :maxdepth: 1
+    :caption: Miscellaneous
 
     faq
-
---------------------------------------------------------------------------------
-
-.. raw:: html
-
-   </div>

docs/Tags-Categories.rst → docs/tags-categories.rst

@@ -9,6 +9,9 @@ handled according to their characteristics. To make it possible to write code
 that tailors its approach according to the Treant it encounters, we can use
 tags and categories.
 
+
+Using tags
+==========
 Tags are individual strings that describe a Treant. Using our Treant
 ``sprout`` as an example, we can add many tags at once ::
 
@@ -26,6 +29,21 @@ They can be iterated through as well ::
     mirky
     misty
 
+Or checked for membership ::
+
+    >>> 'mirky' in s.tags
+    True
+
+Since the tags of a Treant behave as a set, we can do set operations directly ::
+
+    >>> 
+
+API Reference: Tags
+-------------------
+See the :ref:`Tags_api` API reference for more details.
+
+Using categories
+================
 Categories are key-value pairs. They are particularly useful as switches for
 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
@@ -47,23 +65,12 @@ The keys for categories must be strings, but the values may be strings, numbers
 this is used in aggregations (see :ref:`Bundles`) to indicate keys that are
 absent.
 
-Tags and categories are especially useful for filtering and grouping Treants.
-See :ref:`Bundles` for the details on how to flexibly do this.
-
-Reference: Tags
-===============
-The class :class:`datreant.core.limbs.Tags` is the interface used by Treants to
-access their tags. 
+API Reference: Categories
+-------------------------
+See the :ref:`Categories_api` API reference for more details.
 
-.. autoclass:: datreant.core.limbs.Tags
-    :members:
-    :inherited-members:
 
-Reference: Categories
-=====================
-The class :class:`datreant.core.limbs.Categories` is the interface used by
-Treants to access their categories.
-
-.. autoclass:: datreant.core.limbs.Categories
-    :members:
-    :inherited-members:
+Filtering and grouping on tags and categories
+=============================================
+Tags and categories are especially useful for filtering and grouping Treants.
+See :ref:`Bundles` for the details on how to flexibly do this.

docs/Treants.rst → docs/treants.rst

@@ -84,10 +84,7 @@ uuid as well, this is generally not recommended.
 
 Other components, such as the Treant's tags and categories, are stored internally in
 the state file (see :ref:`tags_categories` for more on these).
-
 
-Reference: Treant
-=================
-.. autoclass:: datreant.core.Treant
-    :members:
-    :inherited-members:
+API Reference: Treant
+=====================
+See the :ref:`Treant_api` API reference for more details.

docs/Trees.rst → docs/trees.rst

@@ -28,7 +28,7 @@ necessarily have to exist. Just as with Treants, more than one instance
 of a Tree or Leaf can point to the same place.
 
 
-Working with paths
+Working with Trees 
 ==================
 **Tree** objects can be used to introspect downward into their directory
 structure. Since a Tree is essentially a container for its own child Trees and
@@ -66,6 +66,10 @@ in which case whether a Tree or Leaf is returned is dependent on an ending
           sensitive to ending ``/`` separators to determine whether to give a
           Tree or a Leaf.
 
+API Reference: Tree
+-------------------
+See the :ref:`Tree_api` API reference for more details.
+
 
 A Treant is a Tree
 ==================
@@ -100,14 +104,7 @@ File operations with Leaves
 ===========================
 
 
-Reference: Tree
-===============
-.. autoclass:: datreant.core.Tree
-    :members:
-    :inherited-members:
+API Reference: Leaf 
+-------------------
+See the :ref:`Leaf_api` API reference for more details.
 
-Reference: Leaf
-===============
-.. autoclass:: datreant.core.Leaf
-    :members:
-    :inherited-members: