Added docs for Collections.

diff --git a/docs/models/collections.rst b/docs/models/collections.rst
new file mode 100644 (file)
index 0000000..0519494
--- /dev/null
+++ b/docs/models/collections.rst
@@ -0,0 +1,8 @@
+Collections
+===========
+
+.. automodule:: philo.models.collections
+       :members: Collection, CollectionMember, CollectionMemberManager
+
+.. autoclass:: CollectionMemberManager
+       :members:
\ No newline at end of file

diff --git a/docs/models/intro.rst b/docs/models/intro.rst
index 49b2ac1..31415a6 100644 (file)
--- a/docs/models/intro.rst
+++ b/docs/models/intro.rst
@@ -8,6 +8,7 @@ Contents:
    
    entities
    nodes-and-views
+   collections
 
 
 .. :module: philo.models

diff --git a/philo/models/base.py b/philo/models/base.py
index 466b60a..46e9ac5 100644 (file)
--- a/philo/models/base.py
+++ b/philo/models/base.py
@@ -340,7 +340,7 @@ class TreeManager(models.Manager):
        
        def get_with_path(self, path, root=None, absolute_result=True, pathsep='/', field='slug'):
                """
-               If ``absolute_result`` is ``True``, returns the object at ``path`` (starting at ``root``) or raises a :exception:`DoesNotExist` exception. Otherwise, returns a tuple containing the deepest object found along ``path`` (or ``root`` if no deeper object is found) and the remainder of the path after that object as a string (or None if there is no remaining path).
+               If ``absolute_result`` is ``True``, returns the object at ``path`` (starting at ``root``) or raises a :class:`DoesNotExist` exception. Otherwise, returns a tuple containing the deepest object found along ``path`` (or ``root`` if no deeper object is found) and the remainder of the path after that object as a string (or None if there is no remaining path).
                
                .. note:: If you are looking for something with an exact path, it is faster to use absolute_result=True, unless the path depth is over ~40, in which case the high cost of the absolute query may make a binary search (i.e. non-absolute) faster.
                

diff --git a/philo/models/collections.py b/philo/models/collections.py
index 3513cb4..7c773b3 100644 (file)
--- a/philo/models/collections.py
+++ b/philo/models/collections.py
@@ -8,11 +8,18 @@ from philo.utils import fattr
 
 
 class Collection(models.Model):
+       """
+       Collections are curated ordered groupings of arbitrary models.
+       
+       """
+       #: :class:`CharField` with max_length 255
        name = models.CharField(max_length=255)
+       #: Optional :class:`TextField`
        description = models.TextField(blank=True, null=True)
        
        @fattr(short_description='Members')
        def get_count(self):
+               """Returns the number of items in the collection."""
                return self.members.count()
        
        def __unicode__(self):
@@ -26,15 +33,37 @@ class CollectionMemberManager(models.Manager):
        use_for_related_fields = True
 
        def with_model(self, model):
+               """
+               Given a model class or instance, returns a queryset of all instances of that model which have collection members in this manager's scope.
+               
+               Example::
+               
+                       >>> from philo.models import Collection
+                       >>> from django.contrib.auth.models import User
+                       >>> collection = Collection.objects.get(name="Foo")
+                       >>> collection.members.all()
+                       [<CollectionMember: Foo - user1>, <CollectionMember: Foo - user2>, <CollectionMember: Foo - Spam & Eggs>]
+                       >>> collection.members.with_model(User)
+                       [<User: user1>, <User: user2>]
+               
+               """
                return model._default_manager.filter(pk__in=self.filter(member_content_type=ContentType.objects.get_for_model(model)).values_list('member_object_id', flat=True))
 
 
 class CollectionMember(models.Model):
+       """
+       The collection member model represents a generic link from a :class:`Collection` to an arbitrary model instance with an attached order.
+       
+       """
+       #: A :class:`CollectionMemberManager` instance
        objects = CollectionMemberManager()
+       #: :class:`ForeignKey` to a :class:`Collection` instance.
        collection = models.ForeignKey(Collection, related_name='members')
+       #: The numerical index of the item within the collection (optional).
        index = models.PositiveIntegerField(verbose_name='Index', help_text='This will determine the ordering of the item within the collection. (Optional)', null=True, blank=True)
        member_content_type = models.ForeignKey(ContentType, limit_choices_to=value_content_type_limiter, verbose_name='Member type')
        member_object_id = models.PositiveIntegerField(verbose_name='Member ID')
+       #: :class:`GenericForeignKey` to an arbitrary model instance.
        member = generic.GenericForeignKey('member_content_type', 'member_object_id')
        
        def __unicode__(self):