From dbd3de7f0ae22f42561d64e80826fce4036ff997 Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Mon, 6 Jan 2025 16:49:53 -0500
Subject: [PATCH] wip docs

---
 .pre-commit-config.yaml         |  2 +-
 docs/source/_ext/djangodocs.py  |  5 +++
 docs/source/embedded-models.rst | 55 +++++++++++++++++++++++++++++++++
 docs/source/fields.rst          | 45 +++++++++++++++++++++++++++
 docs/source/index.rst           |  1 +
 5 files changed, 107 insertions(+), 1 deletion(-)
 create mode 100644 docs/source/embedded-models.rst

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 2ceb70d9..782c31ca 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -44,7 +44,7 @@ repos:
   hooks:
   - id: rstcheck
     additional_dependencies: [sphinx]
-    args: ["--ignore-directives=fieldlookup,setting", "--ignore-roles=lookup,setting"]
+    args: ["--ignore-directives=fieldlookup", "--ignore-roles=djadmin,lookup,setting"]
 
 # We use the Python version instead of the original version which seems to require Docker
 # https://github.com/koalaman/shellcheck-precommit
diff --git a/docs/source/_ext/djangodocs.py b/docs/source/_ext/djangodocs.py
index fda464d8..fc89c24c 100644
--- a/docs/source/_ext/djangodocs.py
+++ b/docs/source/_ext/djangodocs.py
@@ -1,4 +1,9 @@
 def setup(app):
+    app.add_object_type(
+        directivename="django-admin",
+        rolename="djadmin",
+        indextemplate="pair: %s; django-admin command",
+    )
     app.add_crossref_type(
         directivename="fieldlookup",
         rolename="lookup",
diff --git a/docs/source/embedded-models.rst b/docs/source/embedded-models.rst
new file mode 100644
index 00000000..08e6891b
--- /dev/null
+++ b/docs/source/embedded-models.rst
@@ -0,0 +1,55 @@
+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_backend.fields import EmbeddedModelField
+
+   class Customer(models.Model):
+       name = models.CharField(...)
+       address = EmbeddedModelField("Address")
+       ...
+
+   class Address(models.Model):
+       ...
+       city = models.CharField(...)
+
+
+The API is similar to that of Django's relational fields::
+
+   >>> Customer.objects.create(name="Bob", address=Address(city="New York", ...), ...)
+   >>> 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``
+-------------------------------
+
+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")
diff --git a/docs/source/fields.rst b/docs/source/fields.rst
index 39f965a7..99fe3599 100644
--- a/docs/source/fields.rst
+++ b/docs/source/fields.rst
@@ -210,6 +210,51 @@ transform do not change. For example:
 
 These indexes use 0-based indexing.
 
+``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. It can be either a concrete model
+        class or a :ref:`lazy reference <lazy-relationships>` to a model class.
+
+        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_backend.fields import EmbeddedModelField
+
+            class Address(models.Model):
+                ...
+
+            class Author(models.Model):
+                address = EmbeddedModelField(Address)
+
+            class Book(models.Model):
+                author = EmbeddedModelField(Author)
+
+See :doc:`embedded-models` for more details and examples.
+
+.. admonition:: Migrations support is limited
+
+    :djadmin:`makemigrations` does not yet detect changes to embedded models.
+
+    After you create a model with an ``EmbeddedModelField`` or add an
+    ``EmbeddedModelField`` to an existing model, no further updates to the
+    embedded model will be made. Using the models above as an example, if you
+    created these models and then added an indexed field to ``Address``,
+    the index created in the nested ``Book`` embed is not created.
+
 ``ObjectIdField``
 -----------------
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 89a1ab23..4e331bd6 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -8,6 +8,7 @@ django-mongodb-backend 5.0.x documentation
    fields
    querysets
    forms
+   embedded-models
 
 Indices and tables
 ==================