Improve and expand the README/docs index.

README.rst

@@ -4,13 +4,58 @@
    :alt: CI status image
    :target: https://github.com/ubernostrum/pwned-passwords-django/actions?query=workflow%3ACI
 
-pwned-passwords-django provides helpers for working with the `Pwned
-Passwords database of Have I Been Pwned
+``pwned-passwords-django`` provides helpers for working with the
+`Pwned Passwords database of Have I Been Pwned
 <https://haveibeenpwned.com/Passwords>`_ in `Django
 <https://www.djangoproject.com/>`_ powered sites. Pwned Passwords is
 an extremely large database of passwords known to have been
 compromised through data breaches, and is useful as a tool for
 rejecting common or weak passwords.
 
-Documentation is `available online
+There are three main components to this application:
+
+* A password validator which integrates with `Django's
+  password-validation tools
+  <https://docs.djangoproject.com/en/5.0/topics/auth/passwords/#module-django.contrib.auth.password_validation>`_
+  and checks the Pwned Passwords database.
+
+* A Django middleware (supporting both sync and async requests) which
+  automatically checks certain request payloads against the Pwned
+  Passwords database.
+
+* An API client providing direct access (both sync and async) to the
+  Pwned Passwords database.
+
+All three use a secure, anonymized API which never transmits any
+password or its full hash to any third party.
+
+
+Usage
+-----
+
+The recommended default configuration is to enable both the validator
+and the automatic password-checking middleware. To do this, make the
+following changes to your Django settings.
+
+First, add the validator to your AUTH_PASSWORD_VALIDATORS list:
+
+.. code-block:: python
+
+   AUTH_PASSWORD_VALIDATORS = [
+       # ... other password validators ...
+       {
+           "NAME": "pwned_passwords_django.validators.PwnedPasswordsValidator",
+       },
+   ]
+
+Then, the middleware <middleware> to your MIDDLEWARE list:
+
+.. code-block:: python
+
+   MIDDLEWARE = [
+       # .. other middlewares ...
+       "pwned_passwords_django.middleware.pwned_passwords_middleware",
+   ]
+
+For more details, consult `the full documentation
 <https://pwned-passwords-django.readthedocs.io/>`_.

docs/index.rst

@@ -1,28 +1,59 @@
-pwned-passwords-django |release|
-==================================
+``pwned-passwords-django`` |release|
+====================================
 
-pwned-passwords-django provides helpers for working with the `Pwned
+``pwned-passwords-django`` provides helpers for working with the `Pwned
 Passwords database of Have I Been Pwned
 <https://haveibeenpwned.com/Passwords>`_ in `Django
-<https://www.djangoproject.com/>`_ powered sites. Pwned Passwords is
-an extremely large database of passwords known to have been
-compromised through data breaches, and is useful as a tool for
-rejecting common or weak passwords.
+<https://www.djangoproject.com/>`_ powered sites. Pwned Passwords is an
+extremely large database of passwords known to have been compromised through
+data breaches, and is useful as a tool for rejecting common or weak passwords.
 
 There are three main components to this application:
 
-* :ref:`A password validator <validator>` which checks the Pwned
-  Passwords database.
+* :ref:`A password validator <validator>` which integrates with `Django's
+  password-validation tools
+  <https://docs.djangoproject.com/en/5.0/topics/auth/passwords/#module-django.contrib.auth.password_validation>`_
+  and checks the Pwned Passwords database.
 
-* :ref:`A middleware <middleware>` which automatically checks certain
-  request payloads against the Pwned Passwords database.
+* :ref:`A Django middleware <middleware>` (supporting both sync and async
+  requests) which automatically checks certain request payloads against the
+  Pwned Passwords database.
 
-* :ref:`Code providing direct access <api>` to the Pwned Passwords
-  database.
+* :ref:`An API client <api>` providing direct access (both sync and async) to
+  the Pwned Passwords database.
 
-All three use a secure, anonymized API which never transmits the
-password or its hash to any third party. To learn more, see :ref:`the
-FAQ <faq>`.
+All three use a secure, anonymized API which never transmits any password or
+its full hash to any third party. To learn more, see :ref:`the FAQ <faq>`.
+
+
+Usage
+-----
+
+The recommended default 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",
+       },
+   ]
+
+Then, add :ref:`the middleware <middleware>` to your :setting:`MIDDLEWARE`
+list:
+
+.. code-block:: python
+
+   MIDDLEWARE = [
+       # .. other middlewares ...
+       "pwned_passwords_django.middleware.pwned_passwords_middleware",
+   ]
 
 
 Documentation contents