Added API Reference to docs

.gitignore

@@ -1,3 +1,4 @@
 *.pyc
 .*.swp
 docs/.build
+docs/_build

docs/Makefile

@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = .build
+BUILDDIR      = _build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4

docs/apireference.rst

@@ -0,0 +1,46 @@
+API Reference
+=============
+
+Connecting
+----------
+
+.. autofunction:: mongoengine.connect
+
+Documents
+---------
+
+.. autoclass:: mongoengine.Document
+   :members:
+
+   .. attribute:: objects
+
+      A :class:`~mongoengine.queryset.QuerySet` object that is created lazily 
+      on access.
+
+.. autoclass:: mongoengine.EmbeddedDocument
+   :members:
+
+Querying
+--------
+
+.. autoclass:: mongoengine.queryset.QuerySet
+   :members:
+
+Fields
+------
+
+.. autoclass:: mongoengine.StringField
+
+.. autoclass:: mongoengine.IntField
+
+.. autoclass:: mongoengine.FloatField
+
+.. autoclass:: mongoengine.DateTimeField
+
+.. autoclass:: mongoengine.EmbeddedDocumentField
+
+.. autoclass:: mongoengine.ListField
+
+.. autoclass:: mongoengine.ObjectIdField
+
+.. autoclass:: mongoengine.ReferenceField

docs/conf.py

@@ -16,13 +16,13 @@ import sys, os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.abspath('..'))
 
 # -- General configuration -----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['sphinx.ext.autodoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['.templates']
@@ -64,7 +64,7 @@ release = '0.1'
 
 # List of directories, relative to source directory, that shouldn't be searched
 # for source files.
-exclude_trees = ['.build']
+exclude_trees = ['_build']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -99,7 +99,7 @@ html_theme = 'nature'
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['.themes']
+html_theme_path = ['_themes']
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -120,7 +120,7 @@ html_theme_path = ['.themes']
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['.static']
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

docs/index.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to MongoEngine's documentation!
+MongoEngine User Documentation
 =======================================
 
 Contents:
@@ -12,6 +12,7 @@ Contents:
    :maxdepth: 2
 
    tutorial.rst
+   apireference.rst
 
 Indices and tables
 ==================

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