Expand/reorganize documentation.

This adds a usage guide with a bit more detail than the index/README,
and explicitly organizes the documentation sidebar in a more useful
way.

Author: ubernostrum

docs/api.rst

@@ -2,8 +2,8 @@
 
 .. _api:
 
-Using the Pwned Passwords API directly
-======================================
+Direct Pwned Passwords API access
+=================================
 
 If :ref:`the validator <validator>` and :ref:`middleware <middleware>` do not
 meet your needs, you can also directly check a password against Pwned

docs/changelog.rst

@@ -73,6 +73,8 @@ Released May 2024
 
 * Supported Django versions are now 4.2 and 5.0.
 
+* Expanded/reorganized documentation.
+
 
 Releases not under DjangoVer
 ----------------------------

docs/faq.rst

@@ -144,7 +144,7 @@ for Python 3.10 only, you could run:
 
 By default, ``nox`` will only run the tasks whose associated Python versions
 are available on your system. For example, if you have only Python 3.8 and 3.9
-installed, test runs for Python 3.7, 3.10, and 3.11 would be skipped.
+installed, test runs for Python 3.10, 3.11, and 3.12 would be skipped.
 
 
 How am I allowed to use this code?

docs/index.rst

@@ -60,14 +60,26 @@ Documentation contents
 ----------------------
 
 .. toctree::
+   :caption: Installation and usage
    :maxdepth: 1
 
    install
+   usage
+
+.. toctree::
+   :caption: API reference
+   :maxdepth: 1
+
    validator
    middleware
    api
    exceptions
    settings
+
+.. toctree::
+   :caption: Other documentation
+   :maxdepth: 1
+
    faq
    changelog
 

docs/middleware.rst

@@ -3,8 +3,8 @@
 .. _middleware:
 
 
-Using the middleware
-====================
+The password-checking middleware
+================================
 
 To help with situations where a potentially-compromised password is used
 :ref:`in ways Django's password validators won't catch

docs/usage.rst

@@ -0,0 +1,68 @@
+.. _usage:
+
+
+Usage guide
+===========
+
+The recommended configuration is to enable both :ref:`the password validator
+<validator>` and :ref:`the automatic password-checking middleware
+<middleware>`. To do this, make the following changes to your Django settings.
+
+First, add :ref:`the validator <validator>` to your
+:setting:`AUTH_PASSWORD_VALIDATORS` list:
+
+.. code-block:: python
+
+   AUTH_PASSWORD_VALIDATORS = [
+       # ... other password validators ...
+       {
+           "NAME": "pwned_passwords_django.validators.PwnedPasswordsValidator",
+       },
+   ]
+
+This will cause user creation (provided it's done via Django's built-in
+:class:`~django.contrib.auth.forms.UserCreationForm` or a subclass, or via
+Django's ``createsuperuser`` management command) and password changes (via the
+built-in Django password-change views/forms, and the ``changepassword``
+management comment) to check the Pwned Passwords database, and reject any
+password found there.
+
+Then, add :ref:`the middleware <middleware>` to your :setting:`MIDDLEWARE`
+list:
+
+.. code-block:: python
+
+   MIDDLEWARE = [
+       # .. other middlewares ...
+       "pwned_passwords_django.middleware.pwned_passwords_middleware",
+   ]
+
+This will add the attribute ``pwned_passwords`` to every Django
+:class:`~django.http.HttpRequest` object. The value of this attribute will be a
+:class:`list` of :class:`str`, where each item in the list is the name of a
+field in ``request.POST`` believed to contain a compromised password. If the
+request method was not ``POST``, did not appear to contain any passwords, or no
+compromised passwords were detected, the ``request.pwned_passwords`` list will
+be empty.
+
+
+Identifying passwords in request payloads
+-----------------------------------------
+
+By default, the middleware checks any field in ``request.POST`` whose name is a
+case-insensitive match for the regex ``r"PASS"``. This will catch many common
+password field names, such as ``"password"``, ``"passphrase"``, and so on. But
+if your site uses something significantly different, you will need to configure
+``pwned-passwords-django`` to check for it. You can do this by specifying the
+Django setting ``PWNED_PASSWORDS`` as a dictionary, and placing a regex -- as a
+string, not as a compiled regex object -- in the key ``"PASSWORD_REGEX"`` of
+that dictionary. For example, if your site uses a field named ``"token"``
+for its passwords, you could specify this in your Django settings:
+
+.. code-block:: python
+
+   PWNED_PASSWORDS = {
+       "PASSWORD_REGEX": r"token",
+   }
+
+See :ref:`the settings documentation <settings>` for full details.

docs/validator.rst

@@ -3,8 +3,8 @@
 .. _validator:
 
 
-Using the password validator
-============================
+The password validator
+======================
 
 .. class:: PwnedPasswordsValidator