Update docs to cover wagtail_site tag, find_for_request and deprecation of SiteMiddleware

docs/reference/pages/model_reference.rst

@@ -259,9 +259,12 @@ In addition to the model fields provided, ``Page`` has many properties and metho
 
 The ``Site`` model is useful for multi-site installations as it allows an administrator to configure which part of the tree to use for each hostname that the server responds on.
 
-This configuration is used by the :class:`~wagtail.core.middleware.SiteMiddleware` middleware class which checks each request against this configuration and appends the Site object to the Django request object. (deprecated)
+The :meth:`~wagtail.core.models.Site.find_for_request` function returns the Site object that will handle the given HTTP request.
+
+.. versionchanged:: 2.9
+
+  Previous versions of Wagtail required the middleware class :class:`~wagtail.core.middleware.SiteMiddleware`, which pre-populated ``request.site`` with the site object. This is now deprecated, to avoid redundant database queries and potential clashes with Django's Sites framework.
 
-As of wagtail 2.6 use the :meth:`~wagtail.core.models.Site.find_for_request` function to get the current wagtail Site. This function will check at the first call which Site to return for a given Django request object.
 
 Database fields
 ~~~~~~~~~~~~~~~

docs/topics/writing_templates.rst

@@ -218,6 +218,26 @@ Used to load anything from your static files directory. Use of this tag avoids r
 Notice that the full path name is not required and the path snippet you enter only need begin with the parent app's directory name.
 
 
+Multi-site support
+~~~~~~~~~~~~~~~~~~
+
+.. _wagtail_site_tag:
+
+``wagtail_site``
+----------------
+
+Returns the Site object corresponding to the current request.
+
+.. code-block:: html+django
+
+    {% load wagtailcore_tags %}
+
+    {% wagtail_site as current_site %}
+
+.. versionadded:: 2.9
+
+  In previous versions, the recommended way to refer to the current site was through the ``request.site`` attribute provided by :class:`~wagtail.core.middleware.SiteMiddleware`; this is now deprecated.
+
 .. _wagtailuserbar_tag:
 
 Wagtail User Bar