From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 9 Sep 2020 14:24:15 +0000 (-0400)
Subject: Repair documentation issues
X-Git-Tag: rel_1_4_0b1~118
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=5ed90cb05a1526c854e3e8f84a5c29d0379bfa95;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Repair documentation issues

Fixes some remaining issues detailed at #5428.

Fixes: #5428
Change-Id: I942a64411766fc82f30791eee570747a218af77d
---

diff --git a/doc/build/changelog/unreleased_13/5539.rst b/doc/build/changelog/unreleased_13/5539.rst
index ee3fb134c8..4010fca1f7 100644
--- a/doc/build/changelog/unreleased_13/5539.rst
+++ b/doc/build/changelog/unreleased_13/5539.rst
@@ -2,9 +2,9 @@
     :tags: change, mysql
     :tickets: 5539
 
-	Add new MySQL reserved words: `cube`, `lateral`.
+    Add new MySQL reserved words: `cube`, `lateral`.
 
-	Reference https://dev.mysql.com/doc/refman/8.0/en/keywords.html :
+    Reference https://dev.mysql.com/doc/refman/8.0/en/keywords.html :
 
-	* CUBE (R); became reserved in 8.0.1
-	* LATERAL (R); added in 8.0.14 (reserved)
+    * CUBE (R); became reserved in 8.0.1
+    * LATERAL (R); added in 8.0.14 (reserved)
diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst
index 4ab42399a6..0e5740b1e6 100644
--- a/doc/build/orm/session_transaction.rst
+++ b/doc/build/orm/session_transaction.rst
@@ -653,7 +653,7 @@ entire database interaction is rolled back.
 
 .. versionchanged:: 1.4  This section introduces a new version of the
    "join into an external transaction" recipe that will work equally well
-   for both :term:`2.0 style` and :term:`1.x style`engines and sessions.
+   for both :term:`2.0 style` and :term:`1.x style` engines and sessions.
    The recipe here from previous versions such as 1.3 will also continue to
    work for 1.x engines and sessions.
 
diff --git a/lib/sqlalchemy/sql/ddl.py b/lib/sqlalchemy/sql/ddl.py
index 3c23b50ca8..67c11f6c76 100644
--- a/lib/sqlalchemy/sql/ddl.py
+++ b/lib/sqlalchemy/sql/ddl.py
@@ -94,9 +94,11 @@ class DDLElement(roles.DDLRole, Executable, _DDLCompiles):
 
         :param target:
           Optional, defaults to None.  The target :class:`_schema.SchemaItem`
-          for the execute call.  Will be passed to the ``on`` callable if any,
-          and may also provide string expansion data for the statement.
-          See ``execute_at`` for more information.
+          for the execute call.   This is equivalent to passing the
+          :class:`_schema.SchemaItem` to the :meth:`.DDLElement.against`
+          method and then invoking :meth:`_schema.DDLElement.execute`
+          upon the resulting :class:`_schema.DDLElement` object.  See
+          :meth:`.DDLElement.against` for further detail.
 
         """
 
@@ -110,7 +112,37 @@ class DDLElement(roles.DDLRole, Executable, _DDLCompiles):
 
     @_generative
     def against(self, target):
-        """Return a copy of this DDL against a specific schema item."""
+        """Return a copy of this :class:`_schema.DDLElement` which will include
+        the given target.
+
+        This essentially applies the given item to the ``.target`` attribute
+        of the returned :class:`_schema.DDLElement` object.  This target
+        is then usable by event handlers and compilation routines in order to
+        provide services such as tokenization of a DDL string in terms of a
+        particular :class:`_schema.Table`.
+
+        When a :class:`_schema.DDLElement` object is established as an event
+        handler for the :meth:`_events.DDLEvents.before_create` or
+        :meth:`_events.DDLEvents.after_create` events, and the event
+        then occurs for a given target such as a :class:`_schema.Constraint`
+        or :class:`_schema.Table`, that target is established with a copy
+        of the :class:`_schema.DDLElement` object using this method, which
+        then proceeds to the :meth:`_schema.DDLElement.execute` method
+        in order to invoke the actual DDL instruction.
+
+        :param target: a :class:`_schema.SchemaItem` that will be the subject
+         of a DDL operation.
+
+        :return: a copy of this :class:`_schema.DDLElement` with the
+         ``.target`` attribute assigned to the given
+         :class:`_schema.SchemaItem`.
+
+        .. seealso::
+
+            :class:`_schema.DDL` - uses tokenization against the "target" when
+            processing the DDL string.
+
+        """
 
         self.target = target
 
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index ea3bb0512b..0c808e7a7e 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -4108,9 +4108,11 @@ class Select(
           column with its parent table's (or aliases) name so that name
           conflicts between columns in different tables don't occur.
           The format of the label is ``<tablename>_<column>``.  The "c"
-          collection of the resulting :class:`_expression.Select`
-          object will use these
-          names as well for targeting column members.
+          collection of a :class:`_expression.Subquery` created
+          against this :class:`_expression.Select`
+          object, as well as the :attr:`_expression.Select.selected_columns`
+          collection of the :class:`_expression.Select` itself, will use these
+          names for targeting column members.
 
           This parameter can also be specified on an existing
           :class:`_expression.Select` object using the