stub out docs

Author: timgraham

.pre-commit-config.yaml

@@ -44,6 +44,7 @@ repos:
   hooks:
   - id: rstcheck
     additional_dependencies: [sphinx]
+    args: ["--ignore-directives=fieldlookup", "--ignore-roles=lookup"]
 
 # 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,6 @@
+def setup(app):
+    app.add_crossref_type(
+        directivename="fieldlookup",
+        rolename="lookup",
+        indextemplate="pair: %s; field lookup type",
+    )

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"
 copyright = "2024, The MongoDB Python Team"
@@ -22,6 +29,7 @@
 add_module_names = False
 
 extensions = [
+    "djangodocs",
     "sphinx.ext.intersphinx",
 ]
 

docs/source/fields.rst

@@ -5,6 +5,172 @@ Model field reference
 
 Some MongoDB-specific fields are available in ``django_mongodb.fields``.
 
+``ArrayField``
+--------------
+
+.. class:: ArrayField(base_field, size=None, **options)
+
+    A field for storing lists of data. Most field types can be used, and you
+    pass another field instance as the :attr:`base_field
+    <ArrayField.base_field>`. You may also specify a :attr:`size
+    <ArrayField.size>`. ``ArrayField`` can be nested to store multi-dimensional
+    arrays.
+
+    If you give the field a :attr:`~django.db.models.Field.default`, ensure
+    it's a callable such as ``list`` (for an empty default) or a callable that
+    returns a list (such as a function). Incorrectly using ``default=[]``
+    creates a mutable default that is shared between all instances of
+    ``ArrayField``.
+
+    .. attribute:: base_field
+
+        This is a required argument.
+
+        Specifies the underlying data type and behavior for the array. It
+        should be an instance of a subclass of
+        :class:`~django.db.models.Field`. For example, it could be an
+        :class:`~django.db.models.IntegerField` or a
+        :class:`~django.db.models.CharField`. Most field types are permitted,
+        with the exception of those handling relational data
+        (:class:`~django.db.models.ForeignKey`,
+        :class:`~django.db.models.OneToOneField` and
+        :class:`~django.db.models.ManyToManyField`) and file fields (
+        :class:`~django.db.models.FileField` and
+        :class:`~django.db.models.ImageField`).
+
+        It is possible to nest array fields - you can specify an instance of
+        ``ArrayField`` as the ``base_field``. For example::
+
+            from django.db import models
+            from django_mongodb.fields import ArrayField
+
+
+            class ChessBoard(models.Model):
+                board = ArrayField(
+                    ArrayField(
+                        models.CharField(max_length=10, blank=True),
+                        size=8,
+                    ),
+                    size=8,
+                )
+
+        Transformation of values between the database and the model, validation
+        of data and configuration, and serialization are all delegated to the
+        underlying base field.
+
+    .. attribute:: size
+
+        This is an optional argument.
+
+        If passed, the array will have a maximum size as specified, validated
+        only by forms.
+
+Querying ``ArrayField``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+There are a number of custom lookups and transforms for :class:`ArrayField`.
+We will use the following example model::
+
+    from django.db import models
+    from django_mongodb.fields import ArrayField
+
+
+    class Post(models.Model):
+        name = models.CharField(max_length=200)
+        tags = ArrayField(models.CharField(max_length=200), blank=True)
+
+        def __str__(self):
+            return self.name
+
+.. fieldlookup:: arrayfield.contains
+
+``contains``
+^^^^^^^^^^^^
+
+The :lookup:`contains` lookup is overridden on :class:`ArrayField`. The
+returned objects will be those where the values passed are a subset of the
+data. It uses the ``$setIntersection`` operator. For example:
+
+.. code-block:: pycon
+
+    >>> Post.objects.create(name="First post", tags=["thoughts", "django"])
+    >>> Post.objects.create(name="Second post", tags=["thoughts"])
+    >>> Post.objects.create(name="Third post", tags=["tutorial", "django"])
+
+    >>> Post.objects.filter(tags__contains=["thoughts"])
+    <QuerySet [<Post: First post>, <Post: Second post>]>
+
+    >>> Post.objects.filter(tags__contains=["django"])
+    <QuerySet [<Post: First post>, <Post: Third post>]>
+
+    >>> Post.objects.filter(tags__contains=["django", "thoughts"])
+    <QuerySet [<Post: First post>]>
+
+.. fieldlookup:: arrayfield.len
+
+``len``
+^^^^^^^
+
+Returns the length of the array. The lookups available afterward are those
+available for :class:`~django.db.models.IntegerField`. For example:
+
+.. code-block:: pycon
+
+    >>> Post.objects.create(name="First post", tags=["thoughts", "django"])
+    >>> Post.objects.create(name="Second post", tags=["thoughts"])
+
+    >>> Post.objects.filter(tags__len=1)
+    <QuerySet [<Post: Second post>]>
+
+.. fieldlookup:: arrayfield.index
+
+Index transforms
+^^^^^^^^^^^^^^^^
+
+Index transforms index into the array. Any non-negative integer can be used.
+There are no errors if it exceeds the :attr:`size <ArrayField.size>` of the
+array. The lookups available after the transform are those from the
+:attr:`base_field <ArrayField.base_field>`. For example:
+
+.. code-block:: pycon
+
+    >>> Post.objects.create(name="First post", tags=["thoughts", "django"])
+    >>> Post.objects.create(name="Second post", tags=["thoughts"])
+
+    >>> Post.objects.filter(tags__0="thoughts")
+    <QuerySet [<Post: First post>, <Post: Second post>]>
+
+    >>> Post.objects.filter(tags__1__iexact="Django")
+    <QuerySet [<Post: First post>]>
+
+    >>> Post.objects.filter(tags__276="javascript")
+    <QuerySet []>
+
+These indexes use 0-based indexing.
+
+.. fieldlookup:: arrayfield.slice
+
+Slice transforms
+^^^^^^^^^^^^^^^^
+
+Slice transforms take a slice of the array. Any two non-negative integers can
+be used, separated by a single underscore. The lookups available after the
+transform do not change. For example:
+
+.. code-block:: pycon
+
+    >>> Post.objects.create(name="First post", tags=["thoughts", "django"])
+    >>> Post.objects.create(name="Second post", tags=["thoughts"])
+    >>> Post.objects.create(name="Third post", tags=["django", "python", "thoughts"])
+
+    >>> Post.objects.filter(tags__0_1=["thoughts"])
+    <QuerySet [<Post: First post>, <Post: Second post>]>
+
+    >>> Post.objects.filter(tags__0_2__contains=["thoughts"])
+    <QuerySet [<Post: First post>, <Post: Second post>]>
+
+These indexes use 0-based indexing.
+
 ``ObjectIdField``
 -----------------