Documentation updates for 1.4

* major additions to 1.4 migration doc; removed additional
  verbosity regarding caching methodology and reorganized the
  doc to present itself more as a "what's changed" guide

* as we now have a path for asyncio, update that doc so that
  we aren't spreading obsolete information

* updates to the 2.0 migration guide with latest info, however
  this is still an architecture doc and not a migration guide
  yet, will need further rework.

* start really talking about 1.x vs. 2.0 style everywhere.  Querying
  is most of the docs so this is going to be a prominent
  theme, start getting it to fit in

* Add introductory documentation for ORM example sections as these
  are too sparse

* new documentation for do_orm_execute(), many separate sections,
  adding deprecation notes to before_compile() and similar

* new example suites to illustrate do_orm_execute(),
  with_loader_criteria()

* modernized horizontal sharding examples and added a separate
  example to distinguish between multiple databases and single
  database w/ multiple tables use case

* introducing DEEP ALCHEMY, will use zzzeeksphinx 1.1.6

* no name for the alchemist yet however the dragon's name
  is Flambé

Change-Id: Id6b5c03b1ce9ddb7b280f66792212a0ef0a1c541

2 files changed, 24 insertions, 3 deletions

diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py
index f925df6c5..1baef29af 100644
--- a/lib/sqlalchemy/engine/interfaces.py
+++ b/lib/sqlalchemy/engine/interfaces.py
@@ -953,7 +953,7 @@ class CreateEnginePlugin(object):
         engine = create_engine(
           "mysql+pymysql://scott:tiger@localhost/test?plugin=myplugin")
 
-    Alternatively, the :paramref:`.create_engine.plugins" argument may be
+    Alternatively, the :paramref:`_sa.create_engine.plugins" argument may be
     passed as a list to :func:`_sa.create_engine`::
 
         engine = create_engine(
diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index db546380e..621cba674 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -649,6 +649,11 @@ class Result(InPlaceGenerative):
         it will produce a new :class:`_engine.Result` object each time
         against its stored set of rows.
 
+        .. seealso::
+
+            :ref:`do_orm_execute_re_executing` - example usage within the
+            ORM to implement a result-set cache.
+
         """
         return FrozenResult(self)
 
@@ -1173,12 +1178,28 @@ class FrozenResult(object):
 
         frozen = result.freeze()
 
-        r1 = frozen()
-        r2 = frozen()
+        unfrozen_result_one = frozen()
+
+        for row in unfrozen_result_one:
+            print(row)
+
+        unfrozen_result_two = frozen()
+        rows = unfrozen_result_two.all()
+
         # ... etc
 
     .. versionadded:: 1.4
 
+    .. seealso::
+
+        .. seealso::
+
+            :ref:`do_orm_execute_re_executing` - example usage within the
+            ORM to implement a result-set cache.
+
+            :func:`_orm.loading.merge_frozen_result` - ORM function to merge
+            a frozen result back into a :class:`_orm.Session`.
+
     """
 
     def __init__(self, result):