Finished GridFS Documentation

* Also made GridFS replace test pass

docs/guide/gridfs.rst

@@ -1,11 +1,17 @@
 ======
 GridFS
 ======
+
+.. versionadded:: 0.4
+
+Writing
+-------
+
 GridFS support comes in the form of the :class:`~mongoengine.FileField` field
 object. This field acts as a file-like object and provides a couple of
-different ways of inserting and retrieving data. Metadata such as content-type
-can also be stored alongside the stored files. In the following example, an
-document is created to store details about animals, including a photo:
+different ways of inserting and retrieving data. Arbitrary metadata such as
+content type can also be stored alongside the files. In the following example,
+a document is created to store details about animals, including a photo::
 
     class Animal(Document):
         genus = StringField()
@@ -14,13 +20,64 @@ document is created to store details about animals, including a photo:
 
     marmot = Animal('Marmota', 'Sciuridae')
 
-    marmot_photo = open('marmot.jpg')   # Retrieve a photo from disk
-    marmot.photo = marmot_photo         # Store the photo in the document
+    marmot_photo = open('marmot.jpg', 'r')      # Retrieve a photo from disk
+    marmot.photo = marmot_photo                 # Store the photo in the document
+    marmot.photo.content_type = 'image/jpeg'    # Store metadata
 
     marmot.save()
 
-So adding file data to a document is as easy as adding data to any other 
+Another way of writing to a :class:`~mongoengine.FileField` is to use the
+:func:`put` method. This allows for metadata to be stored in the same call as
+the file::
 
-.. versionadded:: 0.4
+    marmot.photo.put(marmot_photo, content_type='image/jpeg')
+
+    marmot.save()
+
+Retrieval
+---------
+
+So using the :class:`~mongoengine.FileField` is just like using any other
+field. The file can also be retrieved just as easily::
+
+    marmot = Animal.objects('Marmota').first()
+    photo = marmot.photo.read()
+    content_type = marmot.photo.content_type
+
+Streaming
+---------
+
+Streaming data into a :class:`~mongoengine.FileField` is achieved in a
+slightly different manner.  First, a new file must be created by calling the
+:func:`new_file` method. Data can then be written using :func:`write`::
+
+    marmot.photo.new_file()
+    marmot.photo.write('some_image_data')
+    marmot.photo.write('some_more_image_data')
+    marmot.photo.close()
+
+    marmot.photo.save()
+
+Deletion
+--------
+
+Deleting stored files is achieved with the :func:`delete` method::
+
+    marmot.photo.delete()
+
+.. note::
+    The FileField in a Document actually only stores the ID of a file in a
+    separate GridFS collection. This means that deleting a document
+    with a defined FileField does not actually delete the file. You must be
+    careful to delete any files in a Document as above before deleting the
+    Document itself.
 
 
+Replacing files
+---------------
+
+Files can be replaced with the :func:`replace` method. This works just like
+the :func:`put` method so even metadata can (and should) be replaced::
+
+    another_marmot = open('another_marmot.png', 'r')
+    marmot.photo.replace(another_marmot, content_type='image/png')