From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 25 Jan 2014 21:37:30 +0000 (-0500)
Subject: seealsos in the tutorial
X-Git-Tag: rel_0_8_5~38
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a52b2da3d0a0a7f5aa9da424d9657e4c34fc6719;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

seealsos in the tutorial

Conflicts:
	lib/sqlalchemy/sql/selectable.py
---

diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index 7570a5725f..ac3d96020c 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -905,7 +905,6 @@ to "correlate" the inner ``users`` table with the outer one:
 Using Joins
 ============
 
-
 We're halfway along to being able to construct any SELECT expression. The next
 cornerstone of the SELECT is the JOIN expression. We've already been doing
 joins in our examples, by just placing two tables in either the columns clause
@@ -980,6 +979,14 @@ would be using ``OracleDialect``) to use Oracle-specific SQL:
 If you don't know what that SQL means, don't worry ! The secret tribe of
 Oracle DBAs don't want their black magic being found out ;).
 
+.. seealso::
+
+    :func:`.expression.join`
+
+    :func:`.expression.outerjoin`
+
+    :class:`.Join`
+
 Everything Else
 ================
 
@@ -994,9 +1001,12 @@ Bind Parameter Objects
 
 Throughout all these examples, SQLAlchemy is busy creating bind parameters
 wherever literal expressions occur. You can also specify your own bind
-parameters with your own names, and use the same statement repeatedly. The
-database dialect converts to the appropriate named or positional style, as
-here where it converts to positional for SQLite:
+parameters with your own names, and use the same statement repeatedly.
+The :func:`.bindparam` construct is used to produce a bound parameter
+with a given name.  While SQLAlchemy always refers to bound parameters by
+name on the API side, the
+database dialect converts to the appropriate named or positional style
+at execution time, as here where it converts to positional for SQLite:
 
 .. sourcecode:: pycon+sql
 
@@ -1009,7 +1019,7 @@ here where it converts to positional for SQLite:
     ('wendy',)
     {stop}[(2, u'wendy', u'Wendy Williams')]
 
-Another important aspect of bind parameters is that they may be assigned a
+Another important aspect of :func:`.bindparam` is that it may be assigned a
 type. The type of the bind parameter will determine its behavior within
 expressions and also how the data bound to it is processed before being sent
 off to the database:
@@ -1025,7 +1035,7 @@ off to the database:
     {stop}[(2, u'wendy', u'Wendy Williams')]
 
 
-Bind parameters of the same name can also be used multiple times, where only a
+:func:`.bindparam` constructs of the same name can also be used multiple times, where only a
 single named value is needed in the execute parameters:
 
 .. sourcecode:: pycon+sql
@@ -1050,6 +1060,10 @@ single named value is needed in the execute parameters:
     ('jack', 'jack')
     {stop}[(1, u'jack', u'Jack Jones', 1, 1, u'jack@yahoo.com'), (1, u'jack', u'Jack Jones', 2, 1, u'jack@msn.com')]
 
+.. seealso::
+
+    :func:`.bindparam`
+
 Functions
 ---------
 
@@ -1148,13 +1162,16 @@ of our selectable:
     >>> s.compile().params
     {u'x_2': 5, u'y_2': 12, u'y_1': 45, u'x_1': 17}
 
+.. seealso::
+
+    :data:`.func`
 
 Window Functions
 -----------------
 
 Any :class:`.FunctionElement`, including functions generated by
 :data:`~.expression.func`, can be turned into a "window function", that is an
-OVER clause, using the :meth:`~.FunctionElement.over` method:
+OVER clause, using the :meth:`.FunctionElement.over` method:
 
 .. sourcecode:: pycon+sql
 
@@ -1166,6 +1183,12 @@ OVER clause, using the :meth:`~.FunctionElement.over` method:
     SELECT users.id, row_number() OVER (ORDER BY users.name) AS anon_1
     FROM users
 
+.. seealso::
+
+    :func:`.over`
+
+    :meth:`.FunctionElement.over`
+
 Unions and Other Set Operations
 -------------------------------
 
@@ -1258,6 +1281,20 @@ want the "union" to be stated as a subquery:
     ('%@yahoo.com', '%@msn.com', '%@msn.com')
     {stop}[(1, 1, u'jack@yahoo.com')]
 
+.. seealso::
+
+    :func:`.union`
+
+    :func:`.union_all`
+
+    :func:`.intersect`
+
+    :func:`.intersect_all`
+
+    :func:`.except_`
+
+    :func:`.except_all`
+
 .. _scalar_selects:
 
 Scalar Selects
@@ -1310,6 +1347,12 @@ it using :meth:`.SelectBase.label` instead:
     ()
     {stop}[(u'jack', 2), (u'wendy', 2)]
 
+.. seealso::
+
+    :meth:`.Select.as_scalar`
+
+    :meth:`.Select.label`
+
 .. _correlated_subqueries:
 
 Correlated Subqueries