Fixes related to improved sql formatting

Follow up of I07b72e6620bb64e329d6b641afa27631e91c4f16

Change-Id: I1f61974bf9cdc3da5317e546d4f9b649c2029e4d

5 files changed, 118 insertions, 48 deletions

diff --git a/lib/sqlalchemy/sql/_elements_constructors.py b/lib/sqlalchemy/sql/_elements_constructors.py
index 6e5a7bc5e..d97ede868 100644
--- a/lib/sqlalchemy/sql/_elements_constructors.py
+++ b/lib/sqlalchemy/sql/_elements_constructors.py
@@ -1062,27 +1062,33 @@ def extract(field: str, expr: _ColumnExpressionArgument[Any]) -> Extract:
 def false() -> False_:
     """Return a :class:`.False_` construct.
 
-    E.g.::
+    E.g.:
+
+    .. sourcecode:: pycon+sql
 
         >>> from sqlalchemy import false
         >>> print(select(t.c.x).where(false()))
         {printsql}SELECT x FROM t WHERE false
 
     A backend which does not support true/false constants will render as
-    an expression against 1 or 0::
+    an expression against 1 or 0:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(select(t.c.x).where(false()))
         {printsql}SELECT x FROM t WHERE 0 = 1
 
     The :func:`.true` and :func:`.false` constants also feature
     "short circuit" operation within an :func:`.and_` or :func:`.or_`
-    conjunction::
+    conjunction:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(select(t.c.x).where(or_(t.c.x > 5, true())))
-        {printsql}SELECT x FROM t WHERE true
+        {printsql}SELECT x FROM t WHERE true{stop}
 
         >>> print(select(t.c.x).where(and_(t.c.x > 5, false())))
-        {printsql}SELECT x FROM t WHERE false
+        {printsql}SELECT x FROM t WHERE false{stop}
 
     .. versionchanged:: 0.9 :func:`.true` and :func:`.false` feature
        better integrated behavior within conjunctions and on dialects
@@ -1479,27 +1485,33 @@ def text(text: str) -> TextClause:
 def true() -> True_:
     """Return a constant :class:`.True_` construct.
 
-    E.g.::
+    E.g.:
+
+    .. sourcecode:: pycon+sql
 
         >>> from sqlalchemy import true
         >>> print(select(t.c.x).where(true()))
         {printsql}SELECT x FROM t WHERE true
 
     A backend which does not support true/false constants will render as
-    an expression against 1 or 0::
+    an expression against 1 or 0:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(select(t.c.x).where(true()))
         {printsql}SELECT x FROM t WHERE 1 = 1
 
     The :func:`.true` and :func:`.false` constants also feature
     "short circuit" operation within an :func:`.and_` or :func:`.or_`
-    conjunction::
+    conjunction:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(select(t.c.x).where(or_(t.c.x > 5, true())))
-        {printsql}SELECT x FROM t WHERE true
+        {printsql}SELECT x FROM t WHERE true{stop}
 
         >>> print(select(t.c.x).where(and_(t.c.x > 5, false())))
-        {printsql}SELECT x FROM t WHERE false
+        {printsql}SELECT x FROM t WHERE false{stop}
 
     .. versionchanged:: 0.9 :func:`.true` and :func:`.false` feature
        better integrated behavior within conjunctions and on dialects
@@ -1559,7 +1571,9 @@ def type_coerce(
     The above construct will produce a :class:`.TypeCoerce` object, which
     does not modify the rendering in any way on the SQL side, with the
     possible exception of a generated label if used in a columns clause
-    context::
+    context:
+
+    .. sourcecode:: sql
 
         SELECT date_string AS date_string FROM log
 
@@ -1595,16 +1609,18 @@ def type_coerce(
     When using :func:`.type_coerce` with composed expressions, note that
     **parenthesis are not applied**.   If :func:`.type_coerce` is being
     used in an operator context where the parenthesis normally present from
-    CAST are necessary, use the :meth:`.TypeCoerce.self_group` method::
+    CAST are necessary, use the :meth:`.TypeCoerce.self_group` method:
+
+    .. sourcecode:: pycon+sql
 
         >>> some_integer = column("someint", Integer)
         >>> some_string = column("somestr", String)
         >>> expr = type_coerce(some_integer + 5, String) + some_string
         >>> print(expr)
-        someint + :someint_1 || somestr
+        {printsql}someint + :someint_1 || somestr{stop}
         >>> expr = type_coerce(some_integer + 5, String).self_group() + some_string
         >>> print(expr)
-        (someint + :someint_1) || somestr
+        {printsql}(someint + :someint_1) || somestr{stop}
 
     :param expression: A SQL expression, such as a
      :class:`_expression.ColumnElement`
diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 748e9504b..0fa054a2e 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -1219,13 +1219,15 @@ class ColumnElement(
     together with the addition operator ``+`` to produce
     a :class:`.BinaryExpression`.
     Both :class:`.ColumnClause` and :class:`.BinaryExpression` are subclasses
-    of :class:`_expression.ColumnElement`::
+    of :class:`_expression.ColumnElement`:
+
+    .. sourcecode:: pycon+sql
 
         >>> from sqlalchemy.sql import column
         >>> column('a') + column('b')
         <sqlalchemy.sql.expression.BinaryExpression object at 0x101029dd0>
         >>> print(column('a') + column('b'))
-        a + b
+        {printsql}a + b
 
     .. seealso::
 
@@ -3653,13 +3655,15 @@ class BinaryExpression(OperatorExpression[_T]):
     """Represent an expression that is ``LEFT <operator> RIGHT``.
 
     A :class:`.BinaryExpression` is generated automatically
-    whenever two column expressions are used in a Python binary expression::
+    whenever two column expressions are used in a Python binary expression:
+
+    .. sourcecode:: pycon+sql
 
         >>> from sqlalchemy.sql import column
         >>> column('a') + column('b')
         <sqlalchemy.sql.expression.BinaryExpression object at 0x101029dd0>
         >>> print(column('a') + column('b'))
-        a + b
+        {printsql}a + b
 
     """
 
diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py
index 902811037..6ba873e7f 100644
--- a/lib/sqlalchemy/sql/functions.py
+++ b/lib/sqlalchemy/sql/functions.py
@@ -189,7 +189,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
         construct, except no FROM clause is generated; the function is rendered
         in the similar way as a scalar subquery.
 
-        E.g.::
+        E.g.:
+
+        .. sourcecode:: pycon+sql
 
             >>> from sqlalchemy import func, select
             >>> fn = func.jsonb_each("{'k', 'v'}").scalar_table_valued("key")
@@ -214,7 +216,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
         r"""Return a :class:`_sql.TableValuedAlias` representation of this
         :class:`_functions.FunctionElement` with table-valued expressions added.
 
-        e.g.::
+        e.g.:
+
+        .. sourcecode:: pycon+sql
 
             >>> fn = (
             ...     func.generate_series(1, 5).
@@ -223,15 +227,17 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
 
             >>> print(select(fn))
             {printsql}SELECT anon_1.value, anon_1.start, anon_1.stop, anon_1.step
-            FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1
+            FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1{stop}
 
             >>> print(select(fn.c.value, fn.c.stop).where(fn.c.value > 2))
             {printsql}SELECT anon_1.value, anon_1.stop
             FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1
-            WHERE anon_1.value > :value_1
+            WHERE anon_1.value > :value_1{stop}
 
         A WITH ORDINALITY expression may be generated by passing the keyword
-        argument "with_ordinality"::
+        argument "with_ordinality":
+
+        .. sourcecode:: pycon+sql
 
             >>> fn = func.generate_series(4, 1, -1).table_valued("gen", with_ordinality="ordinality")
             >>> print(select(fn))
@@ -296,7 +302,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
         """Return this :class:`_functions.FunctionElement` as a column expression that
         selects from itself as a FROM clause.
 
-        E.g.::
+        E.g.:
+
+        .. sourcecode:: pycon+sql
 
             >>> from sqlalchemy import select, func
             >>> gs = func.generate_series(1, 5, -1).column_valued()
@@ -336,7 +344,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
         r"""The set of columns exported by this :class:`.FunctionElement`.
 
         This is a placeholder collection that allows the function to be
-        placed in the FROM clause of a statement::
+        placed in the FROM clause of a statement:
+
+        .. sourcecode:: pycon+sql
 
             >>> from sqlalchemy import column, select, func
             >>> stmt = select(column('x'), column('y')).select_from(func.myfunction())
@@ -583,7 +593,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
         :meth:`_functions.FunctionElement.table_valued` method first to
         establish named columns.
 
-        e.g.::
+        e.g.:
+
+        .. sourcecode:: pycon+sql
 
             >>> from sqlalchemy import func, select, column
             >>> data_view = func.unnest([1, 2, 3]).alias("data_view")
@@ -592,7 +604,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
             FROM unnest(:unnest_1) AS data_view
 
         The :meth:`_functions.FunctionElement.column_valued` method provides
-        a shortcut for the above pattern::
+        a shortcut for the above pattern:
+
+        .. sourcecode:: pycon+sql
 
             >>> data_view = func.unnest([1, 2, 3]).column_valued("data_view")
             >>> print(select(data_view))
@@ -763,13 +777,17 @@ class _FunctionGenerator:
     """Generate SQL function expressions.
 
     :data:`.func` is a special object instance which generates SQL
-    functions based on name-based attributes, e.g.::
+    functions based on name-based attributes, e.g.:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(func.count(1))
-        count(:param_1)
+        {printsql}count(:param_1)
 
     The returned object is an instance of :class:`.Function`, and  is a
-    column-oriented SQL element like any other, and is used in that way::
+    column-oriented SQL element like any other, and is used in that way:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(select(func.count(table.c.id)))
         {printsql}SELECT count(sometable.id) FROM sometable
@@ -777,13 +795,17 @@ class _FunctionGenerator:
     Any name can be given to :data:`.func`. If the function name is unknown to
     SQLAlchemy, it will be rendered exactly as is. For common SQL functions
     which SQLAlchemy is aware of, the name may be interpreted as a *generic
-    function* which will be compiled appropriately to the target database::
+    function* which will be compiled appropriately to the target database:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(func.current_timestamp())
         {printsql}CURRENT_TIMESTAMP
 
     To call functions which are present in dot-separated packages,
-    specify them in the same manner::
+    specify them in the same manner:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(func.stats.yield_curve(5, 10))
         {printsql}stats.yield_curve(:yield_curve_1, :yield_curve_2)
@@ -794,6 +816,8 @@ class _FunctionGenerator:
     treated as a string in expressions, specify
     :class:`~sqlalchemy.types.Unicode` as the type:
 
+    .. sourcecode:: pycon+sql
+
         >>> print(func.my_string(u'hi', type_=Unicode) + ' ' +
         ...       func.my_string(u'there', type_=Unicode))
         {printsql}my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3)
@@ -1048,10 +1072,12 @@ class GenericFunction(Function[_T]):
             identifier = "buffer"
             inherit_cache = True
 
-    The above function will render as follows::
+    The above function will render as follows:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(func.geo.buffer())
-        ST_Buffer()
+        {printsql}ST_Buffer()
 
     The name will be rendered as is, however without quoting unless the name
     contains special characters that require quoting.  To force quoting
@@ -1067,10 +1093,12 @@ class GenericFunction(Function[_T]):
             identifier = "buffer"
             inherit_cache = True
 
-    The above function will render as::
+    The above function will render as:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(func.geo.buffer())
-        "ST_Buffer"()
+        {printsql}"ST_Buffer"()
 
     .. versionadded:: 1.3.13  The :class:`.quoted_name` construct is now
        recognized for quoting when used with the "name" attribute of the
@@ -1247,14 +1275,18 @@ class now(GenericFunction[datetime.datetime]):
 class concat(GenericFunction[str]):
     """The SQL CONCAT() function, which concatenates strings.
 
-    E.g.::
+    E.g.:
+
+    .. sourcecode:: pycon+sql
 
         >>> print(select(func.concat('a', 'b')))
         {printsql}SELECT concat(:concat_2, :concat_3) AS concat_1
 
     String concatenation in SQLAlchemy is more commonly available using the
     Python ``+`` operator with string datatypes, which will render a
-    backend-specific concatenation operator, such as ::
+    backend-specific concatenation operator, such as :
+
+    .. sourcecode:: pycon+sql
 
         >>> print(select(literal("a") + "b"))
         {printsql}SELECT :param_1 || :param_2 AS anon_1
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index 54230d58a..8b5cfb520 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -1026,7 +1026,9 @@ class NamedFromClause(FromClause):
         backend dependent, and is supported in various forms by backends
         such as PostgreSQL, Oracle and SQL Server.
 
-        E.g.::
+        E.g.:
+
+        .. sourcecode:: pycon+sql
 
             >>> from sqlalchemy import select, column, func, table
             >>> a = table("a", column("id"), column("x"), column("y"))
@@ -1055,7 +1057,9 @@ class SelectLabelStyle(Enum):
 
     Below, the columns named ``columna`` are both rendered as is, meaning that
     the name ``columna`` can only refer to the first occurrence of this name
-    within a result set, as well as if the statement were used as a subquery::
+    within a result set, as well as if the statement were used as a subquery:
+
+    .. sourcecode:: pycon+sql
 
         >>> from sqlalchemy import table, column, select, true, LABEL_STYLE_NONE
         >>> table1 = table("table1", column("columna"), column("columnb"))
@@ -1078,7 +1082,9 @@ class SelectLabelStyle(Enum):
 
     Below, all column names are given a label so that the two same-named
     columns ``columna`` are disambiguated as ``table1_columna`` and
-    ``table2_columna``::
+    ``table2_columna``:
+
+    .. sourcecode:: pycon+sql
 
         >>> from sqlalchemy import table, column, select, true, LABEL_STYLE_TABLENAME_PLUS_COL
         >>> table1 = table("table1", column("columna"), column("columnb"))
@@ -1105,7 +1111,9 @@ class SelectLabelStyle(Enum):
 
     Below, most column names are left unaffected, except for the second
     occurrence of the name ``columna``, which is labeled using the
-    label ``columna_1`` to disambiguate it from that of ``tablea.columna``::
+    label ``columna_1`` to disambiguate it from that of ``tablea.columna``:
+
+    .. sourcecode:: pycon+sql
 
         >>> from sqlalchemy import table, column, select, true, LABEL_STYLE_DISAMBIGUATE_ONLY
         >>> table1 = table("table1", column("columna"), column("columnb"))
@@ -1714,7 +1722,9 @@ class TableValuedAlias(LateralFromClause, Alias):
     This construct provides for a SQL function that returns columns
     to be used in the FROM clause of a SELECT statement.   The
     object is generated using the :meth:`_functions.FunctionElement.table_valued`
-    method, e.g.::
+    method, e.g.:
+
+    .. sourcecode:: pycon+sql
 
         >>> from sqlalchemy import select, func
         >>> fn = func.json_array_elements_text('["one", "two", "three"]').table_valued("value")
@@ -1770,10 +1780,12 @@ class TableValuedAlias(LateralFromClause, Alias):
         :meth:`_functions.FunctionElement.column_valued` method. See that
         method for further details.
 
-        E.g.::
+        E.g.:
+
+        .. sourcecode:: pycon+sql
 
             >>> print(select(func.some_func().table_valued("value").column))
-            SELECT anon_1 FROM some_func() AS anon_1
+            {printsql}SELECT anon_1 FROM some_func() AS anon_1
 
         .. seealso::
 
@@ -1823,7 +1835,9 @@ class TableValuedAlias(LateralFromClause, Alias):
         """Apply "render derived" to this :class:`_sql.TableValuedAlias`.
 
         This has the effect of the individual column names listed out
-        after the alias name in the "AS" sequence, e.g.::
+        after the alias name in the "AS" sequence, e.g.:
+
+        .. sourcecode:: pycon+sql
 
             >>> print(
             ...     select(
@@ -1836,7 +1850,9 @@ class TableValuedAlias(LateralFromClause, Alias):
 
         The ``with_types`` keyword will render column types inline within
         the alias expression (this syntax currently applies to the
-        PostgreSQL database)::
+        PostgreSQL database):
+
+        .. sourcecode:: pycon+sql
 
             >>> print(
             ...     select(
diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index bcbc7004c..b5c79b4b9 100644
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -202,7 +202,9 @@ class String(Concatenable, TypeEngine[str]):
         :param collation: Optional, a column-level collation for
           use in DDL and CAST expressions.  Renders using the
           COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
-          E.g.::
+          E.g.:
+
+          .. sourcecode:: pycon+sql
 
             >>> from sqlalchemy import cast, select, String
             >>> print(select(cast('some string', String(collation='utf8'))))