add docs

Author: timgraham

.pre-commit-config.yaml

@@ -44,7 +44,7 @@ repos:
   hooks:
   - id: rstcheck
     additional_dependencies: [sphinx]
-    args: ["--ignore-directives=django-admin,fieldlookup,setting", "--ignore-roles=djadmin,lookup,setting"]
+    args: ["--ignore-directives=django-admin,django-admin-option,fieldlookup,setting", "--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

docs/source/_ext/djangodocs.py

@@ -1,3 +1,6 @@
+from sphinx.domains.std import Cmdoption
+
+
 def setup(app):
     app.add_object_type(
         directivename="django-admin",
@@ -14,3 +17,4 @@ def setup(app):
         rolename="setting",
         indextemplate="pair: %s; setting",
     )
+    app.add_directive("django-admin-option", Cmdoption)

docs/source/_static/custom.css

@@ -0,0 +1,4 @@
+p.admonition-title::after {
+    /* Remove colon after admonition titles. */
+    content: none;
+}

docs/source/conf.py

@@ -52,4 +52,4 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "alabaster"
-# html_static_path = ["_static"]
+html_static_path = ["_static"]

docs/source/index.rst

@@ -48,6 +48,11 @@ Forms
 
 - :doc:`ref/forms`
 
+Core functionalities
+====================
+
+- :doc:`topics/cache`
+
 Miscellaneous
 =============
 

docs/source/ref/django-admin.rst

@@ -0,0 +1,28 @@
+===================
+Management commands
+===================
+
+Django MongoDB Backend includes some :doc:`Django management commands
+<django:ref/django-admin>`.
+
+Required configuration
+======================
+
+To make these commands available, you must include ``"django_mongodb_backend"``
+in the :setting:`INSTALLED_APPS` setting.
+
+Available commands
+==================
+
+``createcachecollection``
+-------------------------
+
+.. django-admin:: createcachecollection
+
+Creates the cache collection for use with the :doc:`database cache backend
+</topics/cache>` using the information from your settings file.
+
+.. django-admin-option:: --database DATABASE
+
+Specifies the database in which the cache collection(s) will be created.
+Defaults to ``default``.

docs/source/ref/index.rst

@@ -7,4 +7,5 @@ API reference
 
    models/index
    forms
+   django-admin
    utils

docs/source/topics/cache.rst

@@ -0,0 +1,60 @@
+================
+Database caching
+================
+
+.. class:: django_mongodb_backend.cache.MongoDBCache
+
+You can configure :doc:`Django's caching API <django:topics/cache>` to store
+its data in MongoDB.
+
+To use a database collection as your cache backend:
+
+* Set :setting:`BACKEND <CACHES-BACKEND>` to
+  ``django_mongodb_backend.cache.MongoDBCache``
+
+* Set :setting:`LOCATION <CACHES-LOCATION>` to ``collection_name``, the name of
+  the MongoDB collection. This name can be whatever you want, as long as it's a
+  valid collection name that's not already being used in your database.
+
+In this example, the cache collection's name is ``my_cache_collection``::
+
+    CACHES = {
+        "default": {
+            "BACKEND": "django_mongodb_backend.cache.MongoDBCache",
+            "LOCATION": "my_cache_collection",
+        },
+    }
+
+Unlike other cache backends, the database cache does not support automatic
+culling of expired entries at the database level. Instead, expired cache
+entries are culled each time ``add()``, ``set()``, or ``touch()`` is called.
+
+Creating the cache collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before using the database cache, you must create the cache collection with this
+command:
+
+.. code-block:: shell
+
+    python manage.py createcachecollection
+
+.. admonition:: Didn't work?
+
+    If you get the error ``Unknown command: 'createcachecollection'``, ensure
+    ``"django_mongodb_backend"`` is in your :setting:`INSTALLED_APPS` setting.
+
+This creates a collection in your database with the proper indexes. The name of
+the collection is taken from :setting:`LOCATION <CACHES-LOCATION>`.
+
+If you are using multiple database caches, :djadmin:`createcachecollection`
+creates one collection for each cache.
+
+If you are using multiple databases, :djadmin:`createcachecollection` observes
+the ``allow_migrate()`` method of your database routers (see the
+`Multiple databases`__ section of Django's caching docs).
+
+.. __: https://docs.djangoproject.com/en/5.1/topics/cache/#multiple-databases
+
+Like :djadmin:`migrate`, :djadmin:`createcachecollection` won't touch an
+existing collection. It will only create missing collections.

docs/source/topics/index.rst

@@ -8,5 +8,6 @@ know:
 .. toctree::
    :maxdepth: 2
 
+   cache
    embedded-models
    known-issues

docs/source/topics/known-issues.rst

@@ -97,6 +97,9 @@ Due to the lack of ability to introspect MongoDB collection schema,
 Caching
 =======
 
-:ref:`Database caching <database-caching>` is not supported since the built-in
-database cache backend requires SQL. A custom cache backend for MongoDB will be
-provided in the future.
+:doc:`Database caching</topics/cache>` uses this library's
+:djadmin:`createcachecollection` command rather Django's SQL-specific
+:djadmin:`createcachetable`.
+
+Secondly, you must use the :class:`django_mongodb_backend.cache.MongoDBCache`
+backend rather than Django's built-in database cache backend.