Doc updates

Author: aclark4life

docs/howto/queryable-encryption.rst

@@ -24,10 +24,12 @@ Installation
 ============
 
 In addition to the :doc:`installation </intro/install>` and :doc:`configuration
-</intro/configure>` steps for Django MongoDB Backend, Queryable
-Encryption requires encryption support and a Key Management Service (KMS).
+</intro/configure>` steps already required to use Django MongoDB Backend,
+Queryable Encryption requires the installation of additional dependencies.
+You can install these dependencies by using the ``encryption`` extra when
+installing ``django-mongodb-backend``:
 
-You can install encryption support with the following command::
+.. code-block:: console
 
     pip install django-mongodb-backend[encryption]
 
@@ -36,16 +38,22 @@ You can install encryption support with the following command::
 Configuring the ``DATABASES`` setting
 =====================================
 
-In addition to :ref:`configuring-databases-setting`, you must also configure an
-encrypted database in your :setting:`django:DATABASES` setting.
+In addition to the :ref:`database settings <configuring-databases-setting>`
+already required to use Django MongoDB Backend, you must configure an
+encrypted database to store encrypted data.
 
-This database will be used to store encrypted fields in your models. The
-following example shows how to configure an encrypted database using the
-:class:`AutoEncryptionOpts <pymongo.encryption_options.AutoEncryptionOpts>` from the
-:mod:`encryption_options <pymongo.encryption_options>` module.
+.. admonition:: Encrypted database
 
-This example uses a local KMS provider and a key vault namespace for storing
-encryption keys.
+    An encrypted database is a separate database connection in your
+    :setting:`django:DATABASES` setting that is configured to use
+    :class:`automatic encryption
+    <pymongo.encryption_options.AutoEncryptionOpts>`.
+
+The following example shows how to
+configure an encrypted database using the :class:`AutoEncryptionOpts
+<pymongo.encryption_options.AutoEncryptionOpts>` from the
+:mod:`encryption_options <pymongo.encryption_options>` module with a local KMS
+provider and encryption keys stored in the ``encryption.__keyVault`` collection.
 
 .. code-block:: python
 
@@ -70,7 +78,7 @@ encryption keys.
         "encrypted": {
             "ENGINE": "django_mongodb_backend",
             "HOST": "mongodb+srv://cluster0.example.mongodb.net",
-            "NAME": "encrypted",
+            "NAME": "my_database_encrypted",
             "USER": "my_user",
             "PASSWORD": "my_password",
             "PORT": 27017,
@@ -83,48 +91,57 @@ encryption keys.
         },
     }
 
+.. admonition:: Local KMS provider key
+
+    In the example above, a random key is generated for the local KMS provider
+    using ``os.urandom(96)``. In a production environment, you should securely
+    store and manage your encryption keys.
+
 .. _qe-configuring-database-routers-setting:
 
 Configuring the ``DATABASE_ROUTERS`` setting
 ============================================
 
-Similar to :ref:`configuring-database-routers-setting` for using :doc:`embedded
-models </topics/embedded-models>`, to use Queryable Encryption you must also
-configure the :setting:`django:DATABASE_ROUTERS` setting to route queries to the
-encrypted database.
+Similar to configuring a :ref:`database router
+<configuring-database-routers-setting>` for
+:doc:`embedded models </topics/embedded-models>`, Queryable Encryption
+requires a :setting:`database router <django:DATABASE_ROUTERS>` to route
+queries to the encrypted database.
 
-This is done by adding a custom router that routes queries to the encrypted
-database based on the model's metadata. The following example shows how to
-configure a custom router for Queryable Encryption:
+The following example shows how to
+configure a custom router for the "myapp" application that routes queries to the
+encrypted database.
 
 .. code-block:: python
 
+    # myapp/routers.py
     class EncryptedRouter:
-        """
-        A router for routing queries to the encrypted database for Queryable
-        Encryption.
-        """
-
-        def db_for_read(self, model, **hints):
-            if model._meta.app_label == "myapp":
-                return "encrypted"
-            return None
-
-        db_for_write = db_for_read
-
         def allow_migrate(self, db, app_label, model_name=None, **hints):
             if app_label == "myapp":
                 return db == "encrypted"
-            # Don't create other app's models in the encrypted database.
+            # Prevent migrations on the encrypted database for other apps
             if db == "encrypted":
                 return False
             return None
 
+        def db_for_read(self, model, **hints):
+            if model._meta.app_label == "myapp":
+                return "encrypted"
+            return None
+
         def kms_provider(self, model, **hints):
             return "local"
 
+        db_for_write = db_for_read
+
+
+Then in your Django settings, add the custom router to the
+:setting:`django:DATABASE_ROUTERS` setting:
+
+.. code-block:: python
 
-    DATABASE_ROUTERS = [EncryptedRouter]
+    # settings.py
+    DATABASE_ROUTERS = ["myapp.routers.EncryptedRouter"]
 
 .. _qe-configuring-kms:
 
@@ -138,8 +155,8 @@ options followed by an example of how to use them.
 
 +-------------------------------------------------------------------------+--------------------------------------------------------+
 | :setting:`KMS_CREDENTIALS <DATABASE-KMS-CREDENTIALS>`                   | A dictionary of Key Management Service (KMS)           |
-|                                                                         | credentials configured in the                          |
-|                                                                         | :setting:`django:DATABASES` setting.                   |
+|                                                                         | credentials configured in an inner option of the       |
+|                                                                         | encrypted :setting:`django:DATABASES` setting.         |
 +-------------------------------------------------------------------------+--------------------------------------------------------+
 | :class:`kms_providers <pymongo.encryption_options.AutoEncryptionOpts>`  | A dictionary of KMS provider credentials used to       |
 |                                                                         | access the KMS with                                    |