Docs: Updated content of "sites" framework page.

docs/ref/contrib/sites.txt

@@ -36,7 +36,19 @@ try to get the current site by comparing the
 :attr:`~django.contrib.sites.models.Site.domain` with the host name from
 the :meth:`request.get_host() <django.http.HttpRequest.get_host>` method.
 
-How you use this is up to you, but Django uses it in a couple of ways
+Historically, the original implementation of "sites" required adding a SITE_ID
+in the settings file. This method implied that you would be running multiple
+application/web instances, each with a potentially different :setting:`SITE_ID`.
+Even today, if you opt to specify the :setting:`SITE_ID` in the settings file,
+it will require multiple app/web deployments (to support multiple
+``SITE_IDs``). The newer
+:func:`~django.contrib.sites.shortcuts.get_current_site` function, by comparing
+the domain in every request, enables the ability to serve multiple sites from
+one app instance. To take advantage of this modernized design, omit
+:setting:`SITE_ID` from your settings file and use
+``get_current_site(request)``.
+
+How you use "sites" is up to you, but Django uses it in a couple of ways
 automatically via a couple of conventions.
 
 Example usage
@@ -269,12 +281,15 @@ To enable the sites framework, follow these steps:
 
 #. Add ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting.
 
-#. Define a :setting:`SITE_ID` setting::
+#. Define a :setting:`SITE_ID` setting.\*::
 
     SITE_ID = 1
 
 #. Run :djadmin:`migrate`.
 
+\*Although not in every case. See "Installation Scenarios" in the next
+section.
+
 ``django.contrib.sites`` registers a
 :data:`~django.db.models.signals.post_migrate` signal handler which creates a
 default site named ``example.com`` with the domain ``example.com``. This site
@@ -282,10 +297,37 @@ will also be created after Django creates the test database. To set the
 correct name and domain for your project, you can use a :ref:`data migration
 <data-migrations>`.
 
-In order to serve different sites in production, you'd create a separate
+In order to serve different sites in production, one option is to create a
-settings file with each ``SITE_ID`` (perhaps importing from a common settings
+separate settings file with each ``SITE_ID`` (perhaps importing from a common
-file to avoid duplicating shared settings) and then specify the appropriate
+settings file to avoid duplicating shared settings) and then specify the
-:envvar:`DJANGO_SETTINGS_MODULE` for each site.
+appropriate :envvar:`DJANGO_SETTINGS_MODULE` for each site.
+
+Installation Scenarios
+============================
+
+Scenario 1. As discussed below in "How Django uses the sites framework",
+enabling the framework is strongly encouraged because Django takes advantage
+of it in a few places. Frequently a Django installation is powering only a
+single site. For those cases, define a :setting:`SITE_ID` setting::
+
+    SITE_ID = 1
+
+Scenario 2. When planning to leverage the sites framework the way it is
+intended (with multiple domains) you may still set the :setting:`SITE_ID`
+as before, but since there can only be one :setting:`SITE_ID` in the
+settings file it requires launching multiple instances of your app, which
+increases the complexity of deployments. To be able to host multiple domains
+simultaneously without multiple deployments, it is advantageous to omit the
+:setting:`SITE_ID` setting, and use ``get_current_site(request)``. The
+absence of a :setting:`SITE_ID` variable may create difficulties in local
+development environments, and CI tests, both of which depend on "sites" being
+functional. Consider defining settings this way::
+
+    if CI or LOCAL_DEVELOPMENT:
+        SITE_ID = 1
+
+(Be sure to assign a value to either CI or LOCAL_DEVELOPMENT, in those
+environments.)
 
 Caching the current ``Site`` object
 ===================================
@@ -507,6 +549,10 @@ Finally, to avoid repetitive fallback code, the framework provides a
     :meth:`request.get_host() <django.http.HttpRequest.get_host>` if the
     :setting:`SITE_ID` setting is not defined.
 
+    If :setting:`SITE_ID` is defined, it takes precedence. Therefore, to
+    utilize the full capabilities of ``get_current_site(request)`` to
+    process a ``request``, remove :setting:`SITE_ID` from settings.
+
     Both a domain and a port may be returned by :meth:`request.get_host()
     <django.http.HttpRequest.get_host>` when the Host header has a port
     explicitly specified, e.g. ``example.com:80``. In such cases, if the