Started work on user guide

docs/index.rst

@@ -6,18 +6,20 @@
 MongoEngine User Documentation
 =======================================
 
-Contents:
+MongoEngine is an Object-Document Mapper, written in Python for working with 
+MongoDB. The source is available on 
+`GitHub <http://github.com/hmarr/mongoengine>`_.
 
 .. toctree::
    :maxdepth: 2
 
    tutorial.rst
+   userguide.rst
    apireference.rst
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 

docs/tutorial.rst

@@ -9,14 +9,14 @@ application. As the purpose of this tutorial is to introduce MongoEngine, we'll
 focus on the data-modelling side of the application, leaving out a user
 interface.
 
-Connecting to MongoDB
+Getting started
----------------------
+---------------
 Before we start, make sure that a copy of MongoDB is running in an accessible
 location --- running it locally will be easier, but if that is not an option
 then it may be run on a remote server.
 
 Before we can start using MongoEngine, we need to tell it how to connect to our
-instance of **mongod**. For this we use the :func:`mongoengine.connect`
+instance of :program:`mongod`. For this we use the :func:`~mongoengine.connect`
 function. The only argument we need to provide is the name of the MongoDB
 database to use::
 
@@ -24,11 +24,7 @@ database to use::
     
     connect('tumblelog')
 
-This will connect to a mongod instance running locally on the default port. To
+For more information about connecting to MongoDB see :ref:`guide-connecting`.
-connect to a mongod instance running elsewhere, specify the host and port
-explicitly::
-
-    connect('tumblelog', host='192.168.1.35', port=12345)
 
 Defining our documents
 ----------------------

docs/userguide.rst

@@ -0,0 +1,80 @@
+User Guide
+==========
+
+.. _guide-connecting:
+
+Connecting to MongoDB
+---------------------
+To connect to a running instance of :program:`mongod`, use the
+:func:`~mongoengine.connect` function. The first argument is the name of the
+database to connect to. If the database does not exist, it will be created. If
+the database requires authentication, :attr:`username` and :attr:`password`
+arguments may be provided::
+
+    from mongoengine import connect
+    connect('project1', username='webapp', password='pwd123')
+
+By default, MongoEngine assumes that the :program:`mongod` instance is running
+on **localhost** on port **27017**. If MongoDB is running elsewhere, you may
+provide :attr:`host` and :attr:`port` arguments to
+:func:`~mongoengine.connect`::
+
+    connect('project1', host='192.168.1.35', port=12345)
+
+Defining documents
+------------------
+In MongoDB, a **document** is roughly equivalent to a **row** in an RDBMS. When
+working with relational databases, rows are stored in **tables**, which have a
+strict **schema** that the rows follow. MongoDB stores documents in
+**collections** rather than tables - the principle difference is that no schema 
+is enforced at a database level. 
+
+Defining a document's schema
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+MongoEngine allows you to define schemata for documents as this helps to reduce
+coding errors, and allows for utility methods to be defined on fields which may
+be present. 
+
+To define a schema for a document, create a class that inherits from
+:class:`~mongoengine.Document`. Fields are specified by adding **field
+objects** as class attributes to the document class::
+
+    from mongoengine import *
+    import datetime
+    
+    class Page(Document):
+        title = StringField(max_length=200, required=True)
+        date_modified = DateTimeField(default=datetime.now)
+
+Fields
+^^^^^^
+By default, fields are not required. To make a field mandatory, set the
+:attr:`required` keyword argument of a field to ``True``. Fields also may have
+validation constraints available (such as :attr:`max_length` in the example
+above). Fields may also take default values, which will be used if a value is
+not provided. Default values may optionally be a callable, which will be called
+to retrieve the value (such as in the above example). The field types available 
+are as follows:
+
+* :class:`~mongoengine.StringField`
+* :class:`~mongoengine.IntField`
+* :class:`~mongoengine.FloatField`
+* :class:`~mongoengine.DateTimeField`
+* :class:`~mongoengine.ObjectIdField`
+* :class:`~mongoengine.EmbeddedDocumentField`
+* :class:`~mongoengine.ReferenceField`
+
+Document collections
+^^^^^^^^^^^^^^^^^^^^
+Document classes that inherit **directly** from :class:`~mongoengine.Document`
+will have their own **collection** in the database. The name of the collection
+is by default the name of the class, coverted to lowercase (so in the example
+above, the collection would be called `page`). If you need to change the name
+of the collection (e.g. to use MongoEngine with an existing database), then
+create a class dictionary attribute called :attr:`meta` on your document, and
+set :attr:`collection` to the name of the collection that you want your
+document class to use::
+
+    class Page(Document):
+        title = StringField(max_length=200, required=True)
+        meta = {'collection': 'cmsPage'}

mongoengine/connection.py

@@ -29,15 +29,13 @@ def _get_db():
         raise ConnectionError('Not connected to database')
     return _db
 
-def connect(db=None, username=None, password=None, **kwargs):
+def connect(db, username=None, password=None, **kwargs):
     """Connect to the database specified by the 'db' argument. Connection 
     settings may be provided here as well if the database is not running on
     the default port on localhost. If authentication is needed, provide
     username and password arguments as well.
     """
     global _db
-    if db is None:
-        raise TypeError('"db" argument must be provided to connect()')
 
     _connection_settings.update(kwargs)
     connection = _get_connection()