From a85a848a8c49975183340069386bee58de9dcf1d Mon Sep 17 00:00:00 2001
From: James Bennett <james@b-list.org>
Date: Thu, 7 Nov 2024 17:39:13 -0800
Subject: [PATCH] More documentation updates.

---
 README.rst          | 38 +++++++++++++++++++++++++++++++----
 docs/index.rst      | 49 +++++++++++++++++++++++++++++++--------------
 docs/quickstart.rst |  9 +++++++--
 3 files changed, 75 insertions(+), 21 deletions(-)

diff --git a/README.rst b/README.rst
index 640ce1d5..a9d9c767 100644
--- a/README.rst
+++ b/README.rst
@@ -5,9 +5,39 @@
    :target: https://github.com/ubernostrum/django-registration/actions?query=workflow%3ACI
 
 This is a user-registration application for `Django
-<https://www.djangoproject.com/>`_. There are two registration
-workflows (one-step, and two-step with activation) built in, and it's
-designed to be extensible and support building additional workflows.
+<https://www.djangoproject.com/>`_ sites.
 
-To get started, check out `the documentation
+It has built-in support for:
+
+* User registration with the default Django user model
+
+* User registration with many custom user models
+
+* Two-step (email an activation link) registration
+
+* One-step (register and be immediately logged in) registration
+
+And is designed to be extensible to support use cases beyond what's
+built in.
+
+For example, to enable one-step registration, you'd add
+``"django_registration"`` to your Django ``INSTALLED_APPS`` setting,
+then add the following to your site's root URLconfig:
+
+.. code-block:: python
+
+   from django.urls import include, path
+
+   urlpatterns = [
+       # Other URL patterns ...
+       path("accounts/", include("django_registration.backends.one_step.urls")),
+       path("accounts/", include("django.contrib.auth.urls")),
+       # More URL patterns ...
+   ]
+
+And create a few templates (see `the quick start guide
+<https://django-registration.readthedocs.io/en/stable/quickstart.html>`_
+for details).
+
+For more, check out `the full documentation
 <https://django-registration.readthedocs.io/>`_.
diff --git a/docs/index.rst b/docs/index.rst
index ce9a0c6f..5670835f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,25 +3,44 @@
 django-registration |release|
 =============================
 
-django-registration is an extensible application providing user registration
-functionality for `Django <https://www.djangoproject.com/>`_-powered Web sites.
+``django-registration`` is an extensible application providing user
+registration functionality for `Django <https://www.djangoproject.com/>`_
+sites.
 
-Although nearly all aspects of the registration process are customizable,
-out-of-the-box support is provided for two common use cases:
+It has built-in support for:
 
-* Two-phase registration, consisting of initial signup followed by a
-  confirmation email with instructions for activating the new account.
+* User registration with the default Django user model
 
-* One-phase registration, where a user signs up and is immediately active and
-  logged in.
+* User registration with many custom user models
 
-To get up and running quickly, :ref:`install django-registration <install>`,
-then read :ref:`the quick start guide <quickstart>`, which describes the steps
-necessary to configure django-registration for the built-in workflows. For more
-detailed information, including how to customize the registration process (and
-support for alternate registration systems), read through the documentation
-listed below.
+* Two-step (email an activation link) registration
 
+* One-step (register and be immediately logged in) registration
+
+And is designed to be extensible to support use cases beyond what's
+built in.
+
+For example, to enable one-step registration, you'd add
+``"django_registration"`` to your Django ``INSTALLED_APPS`` setting,
+then add the following to your site's root URLconfig:
+
+.. code-block:: python
+
+   from django.urls import include, path
+
+   urlpatterns = [
+       # Other URL patterns ...
+       path("accounts/", include("django_registration.backends.one_step.urls")),
+       path("accounts/", include("django.contrib.auth.urls")),
+       # More URL patterns ...
+   ]
+
+And create a few templates (see :ref:`the quick start guide <quickstart>` for
+full details).
+
+
+Documentation contents
+----------------------
 
 .. toctree::
    :caption: Installation and configuration
@@ -62,5 +81,5 @@ listed below.
 
    * `Django's authentication documentation
      <https://docs.djangoproject.com/en/stable/topics/auth/>`_. Django's
-     authentication system is used by django-registration's default
+     authentication system is used by ``django-registration``'s default
      configuration.
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 48479c2f..ecfba111 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -58,8 +58,13 @@ To use the activation workflow, you'll need to:
 Required settings
 ~~~~~~~~~~~~~~~~~
 
-Make sure you've added ``"django_registration"`` to your ``INSTALLED_APPS``
-list. Then add the following new setting to your Django settings file:
+Because this workflow sends the activation code via email, you'll need to
+configure `Django's email-sending functionality
+<https://docs.djangoproject.com/en/5.1/topics/email/>`_.
+
+Also, make sure you've added ``"django_registration"`` to your
+``INSTALLED_APPS`` list. Then add the following new setting to your Django
+settings file:
 
 :data:`~django.conf.settings.ACCOUNT_ACTIVATION_DAYS`
    This is an :class:`int` specifying the number of days users will have to