wip docs

Author: timgraham

.pre-commit-config.yaml

@@ -44,6 +44,7 @@ repos:
   hooks:
   - id: rstcheck
     additional_dependencies: [sphinx]
+    args: ["--ignore-directives=django-admin", "--ignore-roles=djadmin"]
 
 # We use the Python version instead of the original version which seems to require Docker
 # https://github.com/koalaman/shellcheck-precommit

docs/source/_ext/djangodocs.py

@@ -0,0 +1,16 @@
+def setup(app):
+    app.add_crossref_type(
+        directivename="fieldlookup",
+        rolename="lookup",
+        indextemplate="pair: %s; field lookup type",
+    )
+    app.add_crossref_type(
+        directivename="setting",
+        rolename="setting",
+        indextemplate="pair: %s; setting",
+    )
+    app.add_object_type(
+        directivename="django-admin",
+        rolename="djadmin",
+        indextemplate="pair: %s; django-admin command",
+    )

docs/source/conf.py

@@ -7,7 +7,14 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 from __future__ import annotations
 
+import sys
 from importlib.metadata import version as _version
+from pathlib import Path
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.append(str((Path(__file__).parent / "_ext").resolve()))
 
 project = "django_mongodb_backend"
 copyright = "2024, The MongoDB Python Team"
@@ -22,6 +29,7 @@
 add_module_names = False
 
 extensions = [
+    "djangodocs",
     "sphinx.ext.intersphinx",
 ]
 

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,49 @@ Model field reference
 
 Some MongoDB-specific fields are available in ``django_mongodb_backend.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. 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.fields import EmbeddedModelField
+
+            class Address(models.Model):
+                ...
+
+            class Author(models.Model):
+                address = EmbeddedModelField(Address)
+
+            class Book(models.Model):
+                author = EmbeddedModelField(Author)
+
+.. 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``
 -----------------
 

docs/source/index.rst

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