added docs for freeze clause

Author: dantownsend

docs/src/piccolo/query_clauses/batch.rst

@@ -33,5 +33,5 @@ There's currently no synchronous version. However, it's easy enough to achieve:
             async for _batch in batch:
                 print(_batch)
 
-    import asyncio
-    asyncio.run(get_batch())
+    from piccolo.utils.sync import run_sync
+    run_sync(get_batch())

docs/src/piccolo/query_clauses/freeze.rst

@@ -0,0 +1,10 @@
+.. _freeze:
+
+freeze
+======
+
+You can use the ``freeze`` clause with any query type.
+
+.. currentmodule:: piccolo.query.base
+
+.. automethod:: Query.freeze

docs/src/piccolo/query_clauses/index.rst

@@ -16,3 +16,4 @@ by modifying the return values.
     ./order_by
     ./where
     ./batch
+    ./freeze

piccolo/query/base.py

@@ -187,7 +187,7 @@ def freeze(self) -> FrozenQuery:
         This is a performance optimisation when the same query is run
         repeatedly. For example:
 
-        .. code-block: python
+        .. code-block:: python
 
             TOP_BANDS = Band.select(
                 Band.name
@@ -207,11 +207,16 @@ async def top_bands(self, request):
 
         It means that Piccolo doesn't have to work as hard each time the query
         is run to generate the corresponding SQL - some of it is cached. If the
-        query is defined within the endpoint, it has to generate the SQL from
-        scratch each time.
+        query is defined within the view/endpoint, it has to generate the SQL
+        from scratch each time.
 
-        Once a query is frozen, you can't apply any more clauses to it (where,
-        limit, output etc).
+        Once a query is frozen, you can't apply any more clauses to it
+        (``where``, ``limit``, ``output`` etc).
+
+        Even though ``freeze`` helps with performance, there are limits to
+        how much it can help, as most of the time is still spent waiting for a
+        response from the database. However, for high throughput apps and data
+        science scripts, it's a worthwhile optimisation.
 
         """
         querystrings = self.querystrings