Added API Reference to docs

mongoengine/document.py

@@ -6,32 +6,58 @@ __all__ = ['Document', 'EmbeddedDocument']
 
 
 class EmbeddedDocument(BaseDocument):
+    """A :class:`~mongoengine.Document` that isn't stored in its own
+    collection.  :class:`~mongoengine.EmbeddedDocument`\ s should be used as
+    fields on :class:`~mongoengine.Document`\ s through the
+    :class:`~mongoengine.EmbeddedDocumentField` field type.
+    """
     
     __metaclass__ = DocumentMetaclass
 
 
 class Document(BaseDocument):
+    """The base class used for defining the structure and properties of
+    collections of documents stored in MongoDB. Inherit from this class, and
+    add fields as class attributes to define a document's structure.
+    Individual documents may then be created by making instances of the
+    :class:`~mongoengine.Document` subclass.
+
+    By default, the MongoDB collection used to store documents created using a
+    :class:`~mongoengine.Document` subclass will be the name of the subclass
+    converted to lowercase. A different collection may be specified by
+    providing :attr:`collection` to the :attr:`meta` dictionary in the class
+    definition.
+
+    A :class:`~mongoengine.Document` subclass may be itself subclassed, to
+    create a specialised version of the document that will be stored in the
+    same collection. To facilitate this behaviour, `_cls` and `_types`
+    fields are added to documents (hidden though the MongoEngine interface
+    though). To disable this behaviour and remove the dependence on the
+    presence of `_cls` and `_types`, set :attr:`allow_inheritance` to
+    ``False`` in the :attr:`meta` dictionary.
+    """
 
     __metaclass__ = TopLevelDocumentMetaclass
 
     def save(self):
-        """Save the document to the database. If the document already exists,
-        it will be updated, otherwise it will be created.
+        """Save the :class:`~mongoengine.Document` to the database. If the
+        document already exists, it will be updated, otherwise it will be
+        created.
         """
         object_id = self.objects._collection.save(self.to_mongo())
         self.id = object_id
 
     def delete(self):
-        """Delete the document from the database. This will only take effect
-        if the document has been previously saved.
+        """Delete the :class:`~mongoengine.Document` from the database. This
+        will only take effect if the document has been previously saved.
         """
         object_id = self._fields['id'].to_mongo(self.id)
         self.__class__.objects(_id=object_id).delete()
 
     @classmethod
     def drop_collection(cls):
-        """Drops the entire collection associated with this Document type from
-        the database.
+        """Drops the entire collection associated with this
+        :class:`~mongoengine.Document` type from the database.
         """
         db = _get_db()
         db.drop_collection(cls._meta['collection'])

mongoengine/fields.py

@@ -87,7 +87,7 @@ class DateTimeField(BaseField):
 
 class EmbeddedDocumentField(BaseField):
     """An embedded document field. Only valid values are subclasses of 
-    EmbeddedDocument. 
+    :class:`~mongoengine.EmbeddedDocument`. 
     """
 
     def __init__(self, document, **kwargs):

mongoengine/queryset.py

@@ -5,7 +5,7 @@ import pymongo
 
 class QuerySet(object):
     """A set of results returned from a query. Wraps a MongoDB cursor, 
-    providing Document objects as the results.
+    providing :class:`~mongoengine.Document` objects as the results.
     """
     
     def __init__(self, document, collection):
@@ -32,7 +32,8 @@ class QuerySet(object):
         return self
 
     def __call__(self, **query):
-        """Filter the selected documents by calling the queryset with a query.
+        """Filter the selected documents by calling the 
+        :class:`~mongoengine.QuerySet` with a query.
         """
         self._query.update(QuerySet._transform_query(**query))
         return self
@@ -76,7 +77,7 @@ class QuerySet(object):
         return result
 
     def with_id(self, object_id):
-        """Retrieve the object matching the _id provided.
+        """Retrieve the object matching the id provided.
         """
         if not isinstance(object_id, pymongo.objectid.ObjectId):
             object_id = pymongo.objectid.ObjectId(object_id)
@@ -87,7 +88,7 @@ class QuerySet(object):
         return result
 
     def next(self):
-        """Wrap the result in a Document object.
+        """Wrap the result in a :class:`~mongoengine.Document` object.
         """
         return self._document._from_son(self._cursor.next())
 
@@ -97,21 +98,22 @@ class QuerySet(object):
         return self._cursor.count()
 
     def limit(self, n):
-        """Limit the number of returned documents to.
+        """Limit the number of returned documents to `n`.
         """
         self._cursor.limit(n)
         # Return self to allow chaining
         return self
 
     def skip(self, n):
-        """Skip n documents before returning the results.
+        """Skip `n` documents before returning the results.
         """
         self._cursor.skip(n)
         return self
 
     def order_by(self, *keys):
-        """Order the QuerySet by the keys. The order may be specified by 
-        prepending each of the keys by a + or a -. Ascending order is assumed.
+        """Order the :class:`~mongoengine.queryset.QuerySet` by the keys. The
+        order may be specified by prepending each of the keys by a + or a -.
+        Ascending order is assumed.
         """
         key_list = []
         for key in keys:
@@ -126,6 +128,9 @@ class QuerySet(object):
         return self
         
     def explain(self, format=False):
+        """Return an explain plan record for the 
+        :class:`~mongoengine.queryset.QuerySet`\ 's cursor.
+        """
         plan = self._cursor.explain()
         if format:
             import pprint