wip docs

docs/source/embedded-models.rst

@@ -0,0 +1,52 @@
+Embedded Models
+===============
+
+Use :class:`~django_mongdob.fields.EmbeddedModelField` to structure your data
+using `embedded documents
+<https://www.mongodb.com/docs/manual/data-modeling/#embedded-data>`_.
+
+The Basics
+----------
+
+Let's consider this example::
+
+   from django_mongodb.fields import EmbeddedModelField
+
+   class Customer(models.Model):
+       name = models.CharField(...)
+       address = EmbeddedModelField('Address')
+       ...
+
+   class Address(models.Model):
+       ...
+       city = models.CharField(...)
+
+
+The API is very natural and is similar to that of Django's relation fields::
+
+   >>> Customer(name='Bob', address=Address(city='New York', ...), ...).save()
+   >>> bob = Customer.objects.get(...)
+   >>> bob.address
+   <Address: Address object>
+   >>> bob.address.city
+   'New York'
+
+Represented in BSON, Bob's structure looks like this:
+
+.. code-block:: js
+
+   {
+     "_id": ObjectId(...),
+     "name": "Bob",
+     "address": {
+       ...
+       "city": "New York"
+     },
+     ...
+   }
+
+
+Querying ``EmbeddedModelField``
+-------------------------------
+
+...

docs/source/fields.rst

@@ -5,6 +5,39 @@ Model field reference
 
 Some MongoDB-specific fields are available in ``django_mongodb.fields``.
 
+``EmbeddedModelField``
+----------------------
+
+.. class:: EmbeddedModelField(embedded_model, **kwargs)
+
+Stores a model of type ``embedded_model``.
+
+   .. attribute:: embedded_model
+
+        This is a required argument.
+
+        Specifies the model class to embed.
+
+        The embedded model cannot have relational fields
+        (:class:`~django.db.models.ForeignKey`,
+        :class:`~django.db.models.OneToOneField` and
+        :class:`~django.db.models.ManyToManyField`).
+
+       It is possible to nest embedded models. For example::
+
+            from django.db import models
+            from django_mongodb.fields import EmbeddedModelField
+
+
+            class ChessBoard(models.Model):
+                board = EmbeddedModelField(
+                    ArrayField(
+                        models.CharField(max_length=10, blank=True),
+                        size=8,
+                    ),
+                    size=8,
+                )
+
 ``ObjectIdField``
 -----------------
 

docs/source/index.rst

@@ -8,6 +8,7 @@ django-mongodb 5.0.x documentation
    fields
    querysets
    forms
+   embedded-models
 
 Indices and tables
 ==================