Fix a wide variety of typos and broken links

Note the PR has a few remaining doc linking issues
listed in the comment that must be addressed separately.

Signed-off-by: aplatkouski <5857672+aplatkouski@users.noreply.github.com>
Closes: #5371
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5371
Pull-request-sha: 7e7d233cf3a0c66980c27db0fcdb3c7d93bc2510

Change-Id: I9c36e8d8804483950db4b42c38ee456e384c59e3

12 files changed, 68 insertions, 62 deletions

diff --git a/doc/build/orm/backref.rst b/doc/build/orm/backref.rst
index 80b395930..65d19eb18 100644
--- a/doc/build/orm/backref.rst
+++ b/doc/build/orm/backref.rst
@@ -216,7 +216,7 @@ However, if we instead created a new ``Address`` object, and associated the
 In the above example, it is **not** as intuitive that the ``Address`` would
 automatically be added to the :class:`.Session`.  However, the backref behavior
 of ``Address.user`` indicates that the ``Address`` object is also appended to
-the ``User.addresses`` collection.  This in turn intiates a **cascade**
+the ``User.addresses`` collection.  This in turn initiates a **cascade**
 operation which indicates that this ``Address`` should be placed into the
 :class:`.Session` as a :term:`pending` object.
 
@@ -228,7 +228,7 @@ to False, as in::
     class User(Base):
         # ...
 
-        addresses = relationship("Address", back_populates="user", cascade_backefs=False)
+        addresses = relationship("Address", back_populates="user", cascade_backrefs=False)
 
 See the example in :ref:`backref_cascade` for further information.
 
diff --git a/doc/build/orm/extensions/baked.rst b/doc/build/orm/extensions/baked.rst
index 951f35e6a..72479e64d 100644
--- a/doc/build/orm/extensions/baked.rst
+++ b/doc/build/orm/extensions/baked.rst
@@ -23,7 +23,7 @@ the caching of the SQL calls and result sets themselves is available in
 .. deprecated:: 1.4  SQLAlchemy 1.4 and 2.0 feature an all-new direct query
    caching system that removes the need for the :class:`.BakedQuery` system.
    Caching is now built in to all Core and ORM queries using the
-   :paramref:`.create_engine.query_cache_size` parameter.
+   :paramref:`_engine.create_engine.query_cache_size` parameter.
 
 
 .. versionadded:: 1.0.0
diff --git a/doc/build/orm/extensions/declarative/api.rst b/doc/build/orm/extensions/declarative/api.rst
index 9998965c4..be97604d3 100644
--- a/doc/build/orm/extensions/declarative/api.rst
+++ b/doc/build/orm/extensions/declarative/api.rst
@@ -103,7 +103,7 @@ Above, classes which inherit from ``DefaultBase`` will use one
 created perhaps within distinct databases::
 
     DefaultBase.metadata.create_all(some_engine)
-    OtherBase.metadata_create_all(some_other_engine)
+    OtherBase.metadata.create_all(some_other_engine)
 
 
 ``__table_cls__``
diff --git a/doc/build/orm/extensions/declarative/relationships.rst b/doc/build/orm/extensions/declarative/relationships.rst
index d33d44245..ac2671c52 100644
--- a/doc/build/orm/extensions/declarative/relationships.rst
+++ b/doc/build/orm/extensions/declarative/relationships.rst
@@ -152,8 +152,8 @@ with declarative as with traditional mappings. The
 traditional way.  The :class:`_schema.Table` usually shares
 the :class:`_schema.MetaData` object used by the declarative base::
 
-    keywords = Table(
-        'keywords', Base.metadata,
+    keyword_author = Table(
+        'keyword_author', Base.metadata,
         Column('author_id', Integer, ForeignKey('authors.id')),
         Column('keyword_id', Integer, ForeignKey('keywords.id'))
         )
@@ -161,7 +161,7 @@ the :class:`_schema.MetaData` object used by the declarative base::
     class Author(Base):
         __tablename__ = 'authors'
         id = Column(Integer, primary_key=True)
-        keywords = relationship("Keyword", secondary=keywords)
+        keywords = relationship("Keyword", secondary=keyword_author)
 
 Like other :func:`~sqlalchemy.orm.relationship` arguments, a string is accepted
 as well, passing the string name of the table as defined in the
@@ -170,7 +170,7 @@ as well, passing the string name of the table as defined in the
     class Author(Base):
         __tablename__ = 'authors'
         id = Column(Integer, primary_key=True)
-        keywords = relationship("Keyword", secondary="keywords")
+        keywords = relationship("Keyword", secondary="keyword_author")
 
 As with traditional mapping, its generally not a good idea to use
 a :class:`_schema.Table` as the "secondary" argument which is also mapped to
diff --git a/doc/build/orm/inheritance_loading.rst b/doc/build/orm/inheritance_loading.rst
index 7e5675c14..3ddff01cf 100644
--- a/doc/build/orm/inheritance_loading.rst
+++ b/doc/build/orm/inheritance_loading.rst
@@ -541,7 +541,7 @@ similarly to the following:
     WHERE employee.id IN (?) ORDER BY employee.id
     (1,)
 
-Combining "selectin" polymorhic loading with query-time
+Combining "selectin" polymorphic loading with query-time
 :func:`_orm.with_polymorphic` usage is also possible (though this is very
 outer-space stuff!); assuming the above mappings had no ``polymorphic_load``
 set up, we could get the same result as follows::
diff --git a/doc/build/orm/internals.rst b/doc/build/orm/internals.rst
index c9683e145..08434d3bb 100644
--- a/doc/build/orm/internals.rst
+++ b/doc/build/orm/internals.rst
@@ -6,7 +6,7 @@ ORM Internals
 Key ORM constructs, not otherwise covered in other
 sections, are listed here.
 
-.. currentmodule: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 .. autoclass:: sqlalchemy.orm.state.AttributeState
     :members:
diff --git a/doc/build/orm/nonstandard_mappings.rst b/doc/build/orm/nonstandard_mappings.rst
index 81679dd01..387a3bf90 100644
--- a/doc/build/orm/nonstandard_mappings.rst
+++ b/doc/build/orm/nonstandard_mappings.rst
@@ -189,7 +189,7 @@ at :ref:`relationship_aliased_class`.
 As far as the use case of a class that can actually be fully persisted
 to different tables under different scenarios, very early versions of
 SQLAlchemy offered a feature for this adapted from Hibernate, known
-as the "entity name" feature.  However, this use case became infeasable
+as the "entity name" feature.  However, this use case became infeasible
 within SQLAlchemy once the mapped class itself became the source of SQL
 expression construction; that is, the class' attributes themselves link
 directly to mapped table columns.   The feature was removed and replaced
diff --git a/doc/build/orm/persistence_techniques.rst b/doc/build/orm/persistence_techniques.rst
index 27c8c382f..c33474f57 100644
--- a/doc/build/orm/persistence_techniques.rst
+++ b/doc/build/orm/persistence_techniques.rst
@@ -98,27 +98,41 @@ The current :class:`~sqlalchemy.engine.Connection` held by the
 
     connection = session.connection()
 
-The examples above deal with a :class:`~sqlalchemy.orm.session.Session` that's
-bound to a single :class:`~sqlalchemy.engine.Engine` or
-:class:`~sqlalchemy.engine.Connection`. To execute statements using a
-:class:`~sqlalchemy.orm.session.Session` which is bound either to multiple
+The examples above deal with a :class:`_orm.Session` that's
+bound to a single :class:`_engine.Engine` or
+:class:`_engine.Connection`. To execute statements using a
+:class:`_orm.Session` which is bound either to multiple
 engines, or none at all (i.e. relies upon bound metadata), both
-:meth:`~.Session.execute` and
-:meth:`~.Session.connection` accept a ``mapper`` keyword
-argument, which is passed a mapped class or
-:class:`~sqlalchemy.orm.mapper.Mapper` instance, which is used to locate the
+:meth:`_orm.Session.execute` and
+:meth:`_orm.Session.connection` accept a dictionary of bind arguments
+:paramref:`_orm.Session.execute.bind_arguments` which may include "mapper"
+which is passed a mapped class or
+:class:`_orm.Mapper` instance, which is used to locate the
 proper context for the desired engine::
 
     Session = sessionmaker()
     session = Session()
 
     # need to specify mapper or class when executing
-    result = session.execute("select * from table where id=:id", {'id':7}, mapper=MyMappedClass)
+    result = session.execute(
+        text("select * from table where id=:id"),
+        {'id':7},
+        bind_arguments={'mapper': MyMappedClass}
+    )
 
-    result = session.execute(select([mytable], mytable.c.id==7), mapper=MyMappedClass)
+    result = session.execute(
+        select([mytable], mytable.c.id==7),
+        bind_arguments={'mapper': MyMappedClass}
+    )
 
     connection = session.connection(MyMappedClass)
 
+.. versionchanged:: 1.4 the ``mapper`` and ``clause`` arguments to
+   :meth:`_orm.Session.execute` are now passed as part of a dictionary
+   sent as the :paramref:`_orm.Session.execute.bind_arguments` parameter.
+   The previous arguments are still accepted however this usage is
+   deprecated.
+
 .. _session_forcing_null:
 
 Forcing NULL on a column with a default
@@ -249,7 +263,7 @@ at :paramref:`_schema.Column.autoincrement`.
 
 For server-generating columns that are not primary key columns or that are not
 simple autoincrementing integer columns, the ORM requires that these columns
-are marked with an appropriate server_default directive that allows the ORM to
+are marked with an appropriate ``server_default`` directive that allows the ORM to
 retrieve this value.   Not all methods are supported on all backends, however,
 so care must be taken to use the appropriate method. The two questions to be
 answered are, 1. is this column part of the primary key or not, and 2. does the
diff --git a/doc/build/orm/session_api.rst b/doc/build/orm/session_api.rst
index 849472e9f..bad816967 100644
--- a/doc/build/orm/session_api.rst
+++ b/doc/build/orm/session_api.rst
@@ -11,37 +11,29 @@ Session and sessionmaker()
     :inherited-members:
 
 .. autoclass:: ORMExecuteState
-   :members:
-
-
-  .. attribute::  session
-
-      The :class:`_orm.Session` in use.
+    :members:
 
-  .. attribute:: statement
+    .. attribute::  session
 
-      The SQL statement being invoked.  For an ORM selection as would
-      be retrieved from :class:`_orm.Query`, this is an instance of
-      :class:`_future.select` that was generated from the ORM query.
+        The :class:`_orm.Session` in use.
 
-  .. attribute:: parameters
+    .. attribute:: statement
 
-      Dictionary of parameters that was passed to :meth:`_orm.Session.execute`.
+        The SQL statement being invoked.  For an ORM selection as would
+        be retrieved from :class:`_orm.Query`, this is an instance of
+        :class:`_future.select` that was generated from the ORM query.
 
-  .. attribute:: execution_options
+    .. attribute:: parameters
 
-      Dictionary of execution options passed to :meth:`_orm.Session.execute`.
-      Note that this dictionary does not include execution options that may
-      be associated with the statement itself, or with any underlying
-      :class:`_engine.Connection` that may be used to invoke this statement.
+        Dictionary of parameters that was passed to :meth:`_orm.Session.execute`.
 
-  .. attribute:: bind_arguments
+    .. attribute:: bind_arguments
 
-      The dictionary passed as the
-      :paramref:`_orm.Session.execute.bind_arguments` dictionary.  This
-      dictionary may be used by extensions to :class:`_orm.Session` to pass
-      arguments that will assist in determining amongst a set of database
-      connections which one should be used to invoke this statement.
+        The dictionary passed as the
+        :paramref:`_orm.Session.execute.bind_arguments` dictionary.  This
+        dictionary may be used by extensions to :class:`_orm.Session` to pass
+        arguments that will assist in determining amongst a set of database
+        connections which one should be used to invoke this statement.
 
 
 .. autoclass:: Session
diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst
index bf57ac686..df157c17c 100644
--- a/doc/build/orm/session_basics.rst
+++ b/doc/build/orm/session_basics.rst
@@ -522,10 +522,10 @@ Adding New or Existing Items
 ----------------------------
 
 :meth:`~.Session.add` is used to place instances in the
-session. For *transient* (i.e. brand new) instances, this will have the effect
+session. For :term:`transient` (i.e. brand new) instances, this will have the effect
 of an INSERT taking place for those instances upon the next flush. For
-instances which are *persistent* (i.e. were loaded by this session), they are
-already present and do not need to be added. Instances which are *detached*
+instances which are :term:`persistent` (i.e. were loaded by this session), they are
+already present and do not need to be added. Instances which are :term:`detached`
 (i.e. have been removed from a session) may be re-associated with a session
 using this method::
 
@@ -632,7 +632,7 @@ illustrated in the example below::
         # ...
 
         addresses = relationship(
-            "Address", cascade="all, delete, delete-orphan")
+            "Address", cascade="all, delete-orphan")
 
     # ...
 
@@ -654,7 +654,7 @@ that this related object is not to shared with any other parent simultaneously::
         # ...
 
         preference = relationship(
-            "Preference", cascade="all, delete, delete-orphan",
+            "Preference", cascade="all, delete-orphan",
             single_parent=True)
 
 
diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst
index 233768f42..06139e0c5 100644
--- a/doc/build/orm/session_transaction.rst
+++ b/doc/build/orm/session_transaction.rst
@@ -403,7 +403,7 @@ has multiple binds or some other custom scheme for :meth:`.Session.get_bind`,
 we can pass additional arguments to :meth:`.Session.connection` in order to
 affect how the bind is procured::
 
-    sess = my_sesssionmaker()
+    sess = my_sessionmaker()
 
     # set up a transaction for the bind associated with
     # the User mapper
diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index 8ea8af4a2..a6ef57bed 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -849,7 +849,7 @@ A number of methods on :class:`_query.Query`
 immediately issue SQL and return a value containing loaded
 database results.  Here's a brief tour:
 
-* :meth:`_query.Query.all()` returns a list:
+* :meth:`_query.Query.all` returns a list:
 
   .. sourcecode:: python+sql
 
@@ -880,7 +880,7 @@ database results.  Here's a brief tour:
             :ref:`faq_query_deduplicating`
 
 
-* :meth:`_query.Query.first()` applies a limit of one and returns
+* :meth:`_query.Query.first` applies a limit of one and returns
   the first result as a scalar:
 
   .. sourcecode:: python+sql
@@ -896,7 +896,7 @@ database results.  Here's a brief tour:
       [...] ('%ed', 1, 0)
       {stop}<User(name='ed', fullname='Ed Jones', nickname='eddie')>
 
-* :meth:`_query.Query.one()` fully fetches all rows, and if not
+* :meth:`_query.Query.one` fully fetches all rows, and if not
   exactly one object identity or composite row is present in the result, raises
   an error.  With multiple rows found:
 
@@ -949,8 +949,8 @@ Literal strings can be used flexibly with
 :class:`~sqlalchemy.orm.query.Query`, by specifying their use
 with the :func:`_expression.text` construct, which is accepted
 by most applicable methods.  For example,
-:meth:`~sqlalchemy.orm.query.Query.filter()` and
-:meth:`~sqlalchemy.orm.query.Query.order_by()`:
+:meth:`_query.Query.filter` and
+:meth:`_query.Query.order_by`:
 
 .. sourcecode:: python+sql
 
@@ -972,7 +972,7 @@ by most applicable methods.  For example,
     fred
 
 Bind parameters can be specified with string-based SQL, using a colon. To
-specify the values, use the :meth:`~sqlalchemy.orm.query.Query.params()`
+specify the values, use the :meth:`_query.Query.params`
 method:
 
 .. sourcecode:: python+sql
@@ -990,9 +990,9 @@ method:
 
 To use an entirely string-based statement, a :func:`_expression.text` construct
 representing a complete statement can be passed to
-:meth:`~sqlalchemy.orm.query.Query.from_statement()`.   Without further
+:meth:`_query.Query.from_statement`.   Without further
 specification, the ORM will match columns in the ORM mapping to the result
-returned by the SQL statement based on column name::
+returned by the SQL statement based on column name:
 
 .. sourcecode:: python+sql
 
@@ -1040,7 +1040,7 @@ Counting
 --------
 
 :class:`~sqlalchemy.orm.query.Query` includes a convenience method for
-counting called :meth:`~sqlalchemy.orm.query.Query.count()`:
+counting called :meth:`_query.Query.count`:
 
 .. sourcecode:: python+sql
 
@@ -1065,7 +1065,7 @@ counting called :meth:`~sqlalchemy.orm.query.Query.count()`:
     and always returns the right answer.  Use ``func.count()`` if a
     particular statement absolutely cannot tolerate the subquery being present.
 
-The :meth:`_query.Query.count()` method is used to determine
+The :meth:`_query.Query.count` method is used to determine
 how many rows the SQL statement would return.   Looking
 at the generated SQL above, SQLAlchemy always places whatever it is we are
 querying into a subquery, then counts the rows from that.   In some cases
@@ -1328,7 +1328,7 @@ The `Wikipedia page on SQL JOIN
 join techniques, several of which we'll illustrate here.
 
 To construct a simple implicit join between ``User`` and ``Address``,
-we can use :meth:`_query.Query.filter()` to equate their related columns together.
+we can use :meth:`_query.Query.filter` to equate their related columns together.
 Below we load the ``User`` and ``Address`` entities at once using this method:
 
 .. sourcecode:: python+sql