add more docs

Author: timgraham

docs/source/ref/models/fields.rst

@@ -256,7 +256,8 @@ These indexes use 0-based indexing.
             class Book(models.Model):
                 author = EmbeddedModelField(Author)
 
-    See :doc:`/topics/embedded-models` for more details and examples.
+    See :ref:`the embedded model topic guide <embeddedmodelfield-example>` for
+    more details and examples.
 
 .. admonition:: Migrations support is limited
 
@@ -290,6 +291,9 @@ These indexes use 0-based indexing.
         If passed, the array will have a maximum size as specified, validated
         by forms and model validation, but not enforced by the database.
 
+    See :ref:`the embedded model topic guide <embeddedmodelarrayfield-example>`
+    for more details and examples.
+
 .. admonition:: Migrations support is limited
 
     As described above for :class:`EmbeddedModelField`,

docs/source/topics/embedded-models.rst

@@ -6,8 +6,13 @@ Use :class:`~django_mongodb_backend.fields.EmbeddedModelField` and
 your data using `embedded documents
 <https://www.mongodb.com/docs/manual/data-modeling/#embedded-data>`_.
 
+.. _embeddedmodelfield-example:
+
+``EmbeddedModelField``
+----------------------
+
 The basics
-----------
+~~~~~~~~~~
 
 Let's consider this example::
 
@@ -47,11 +52,61 @@ Represented in BSON, Bob's structure looks like this:
      ...
    }
 
+Unless explicitly set, embedded models don't have a primary key value.
+
 Querying ``EmbeddedModelField``
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can query into an embedded model using the same double underscore syntax
 as relational fields. For example, to retrieve all customers who have an
 address with the city "New York"::
 
     >>> Customer.objects.filter(address__city="New York")
+
+.. _embeddedmodelarrayfield-example:
+
+``EmbeddedModelArrayField``
+---------------------------
+
+The basics
+~~~~~~~~~~
+
+Let's consider this example::
+
+   from django_mongodb_backend.fields import EmbeddedModelArrayField
+   from django_mongodb_backend.models import EmbeddedModel
+
+   class Customer(models.Model):
+       name = models.CharField(...)
+       addresses = EmbeddedModelArrayField("Address")
+       ...
+
+   class Address(EmbeddedModel):
+       ...
+       city = models.CharField(...)
+
+
+The API is similar to that of Django's relational fields::
+
+   >>> Customer.objects.create(name="Bob", addresses=[Address(city="New York", ...)], ...)
+   >>> bob = Customer.objects.get(name="Bob")
+   >>> bob.addresses
+   [<Address: Address object>]
+   >>> bob.address[0].city
+   'New York'
+
+Represented in BSON, Bob's structure looks like this:
+
+.. code-block:: js
+
+   {
+     "_id": ObjectId(...),
+     "name": "Bob",
+     "address": [{
+       ...
+       "city": "New York"
+     }],
+     ...
+   }
+
+Unless explicitly set, embedded models don't have a primary key value.