wip docs

Author: timgraham

docs/source/conf.py

@@ -17,11 +17,25 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+extensions = [
+    "sphinx.ext.intersphinx",
+]
 
 # templates_path = ["_templates"]
 exclude_patterns = []
 
+intersphinx_mapping = {
+    "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "django": (
+        "https://docs.djangoproject.com/en/5.0/",
+        "http://docs.djangoproject.com/en/5.0/_objects/",
+    ),
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/source/index.rst

@@ -1,16 +1,11 @@
-.. django_mongodb documentation master file, created by
-   sphinx-quickstart on Mon Apr 15 12:38:26 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root ``toctree`` directive.
-
 Welcome to django_mongodb's documentation!
 ==========================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
-
+   querysets
 
 Indices and tables
 ==================

docs/source/querysets.rst

@@ -0,0 +1,33 @@
+``QuerySet`` API reference
+==========================
+
+Some MongoDB-specific ``QuerySet`` methods are available by adding a custom
+:class:`~django.db.models.Manager`, ``MongoManager``, to your model::
+
+    from django.db import models
+
+    from django_mongodb.managers import MongoManager
+
+
+    class MyModel(models.Model):
+        ...
+
+        objects = MongoManager()
+
+
+.. currentmodule:: django_mongodb.queryset.MongoQuerySet
+
+``raw_aggregate()``
+-------------------
+
+.. method:: raw_aggregate(pipeline, using=None)
+
+Similar to :meth:`QuerySet.raw()<django.db.models.query.QuerySet.raw>`, but
+instead of a raw SQL query, this method accepts a pipeline that will be passed
+to :meth:`pymongo.collection.Collection.aggregate`. The pipeline must return
+the necessary fields to construct model instances and may also return
+additional fields that will be added as annotations on the models.
+
+For example, you could write a custom match criteria::
+
+    Post.objects.raw_aggregate([{"$match": {"title": "MongoDB is fun"}}])