Fix almost all read-level sphinx warnings

Partial backport of 43bcb0de1ecc1dc2abd7e7c3eb0c39f3eab9adc0.

Also enables sphinx multiprocess.

Change-Id: I49b1959b9a5fe84fb4c74366da2724284a804936
(cherry picked from commit d56887bcb63808ff6b42e4370ec082a8ef5a41a0)
(cherry picked from commit 17feac57cde73bda9fb5b335fa9b3e62aa5cadad)

32 files changed, 55 insertions, 47 deletions

diff --git a/doc/build/Makefile b/doc/build/Makefile
index cd39b7288..58fdc6c16 100644
--- a/doc/build/Makefile
+++ b/doc/build/Makefile
@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -v
+SPHINXOPTS    = -j auto -v
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = output
diff --git a/doc/build/changelog/changelog_07.rst b/doc/build/changelog/changelog_07.rst
index 2b7654ec2..355894004 100644
--- a/doc/build/changelog/changelog_07.rst
+++ b/doc/build/changelog/changelog_07.rst
@@ -1,62 +1,62 @@
-
 =============
 0.7 Changelog
 =============
 
 .. changelog::
     :version: 0.7.11
+    :released:
 
     .. change::
         :tags: bug, engine
         :tickets: 2851
         :versions: 0.8.3, 0.9.0b1
 
-        The regexp used by the :func:`~sqlalchemy.engine.url.make_url` function now parses
-        ipv6 addresses, e.g. surrounded by brackets.
+      The regexp used by the :func:`~sqlalchemy.engine.url.make_url` function now parses
+      ipv6 addresses, e.g. surrounded by brackets.
 
     .. change::
         :tags: bug, orm
         :tickets: 2807
         :versions: 0.8.3, 0.9.0b1
 
-        Fixed bug where list instrumentation would fail to represent a
-        setslice of ``[0:0]`` correctly, which in particular could occur
-        when using ``insert(0, item)`` with the association proxy.  Due
-        to some quirk in Python collections, the issue was much more likely
-        with Python 3 rather than 2.
+      Fixed bug where list instrumentation would fail to represent a
+      setslice of ``[0:0]`` correctly, which in particular could occur
+      when using ``insert(0, item)`` with the association proxy.  Due
+      to some quirk in Python collections, the issue was much more likely
+      with Python 3 rather than 2.
 
     .. change::
         :tags: bug, sql
         :tickets: 2801
         :versions: 0.8.3, 0.9.0b1
 
-        Fixed regression dating back to 0.7.9 whereby the name of a CTE might
-        not be properly quoted if it was referred to in multiple FROM clauses.
+      Fixed regression dating back to 0.7.9 whereby the name of a CTE might
+      not be properly quoted if it was referred to in multiple FROM clauses.
 
     .. change::
         :tags: mysql, bug
         :tickets: 2791
         :versions: 0.8.3, 0.9.0b1
 
-        Updates to MySQL reserved words for versions 5.5, 5.6, courtesy
-        Hanno Schlichting.
+      Updates to MySQL reserved words for versions 5.5, 5.6, courtesy
+      Hanno Schlichting.
 
     .. change::
         :tags: sql, bug, cte
         :tickets: 2783
         :versions: 0.8.3, 0.9.0b1
 
-        Fixed bug in common table expression system where if the CTE were
-        used only as an ``alias()`` construct, it would not render using the
-        WITH keyword.
+      Fixed bug in common table expression system where if the CTE were
+      used only as an ``alias()`` construct, it would not render using the
+      WITH keyword.
 
     .. change::
         :tags: bug, sql
         :tickets: 2784
         :versions: 0.8.3, 0.9.0b1
 
-        Fixed bug in :class:`.CheckConstraint` DDL where the "quote" flag from a
-        :class:`.Column` object would not be propagated.
+      Fixed bug in :class:`.CheckConstraint` DDL where the "quote" flag from a
+      :class:`.Column` object would not be propagated.
 
     .. change::
         :tags: bug, orm
diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst
index b8d7094d0..26f2fecf9 100644
--- a/doc/build/changelog/changelog_08.rst
+++ b/doc/build/changelog/changelog_08.rst
@@ -1,4 +1,3 @@
-
 =============
 0.8 Changelog
 =============
diff --git a/doc/build/changelog/changelog_09.rst b/doc/build/changelog/changelog_09.rst
index 2e418abd0..52b9a3dee 100644
--- a/doc/build/changelog/changelog_09.rst
+++ b/doc/build/changelog/changelog_09.rst
@@ -7,9 +7,11 @@
     .. include:: changelog_08.rst
         :start-line: 5
 
+
     .. include:: changelog_07.rst
         :start-line: 5
 
+
 .. _unreleased_changelog::
     :version: 0.9.11
 
diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst
index 1ae1f3216..c5945a32c 100644
--- a/doc/build/changelog/changelog_10.rst
+++ b/doc/build/changelog/changelog_10.rst
@@ -1,5 +1,3 @@
-
-
 =============
 1.0 Changelog
 =============
@@ -9,13 +7,16 @@
     .. include:: changelog_09.rst
         :start-line: 5
 
+
     .. include:: changelog_08.rst
         :start-line: 5
 
+
     .. include:: changelog_07.rst
         :start-line: 5
 
 
+
 .. changelog::
     :version: 1.0.19
     :released: August 3, 2017
diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst
index 9f3e73303..e4d91b2e4 100644
--- a/doc/build/changelog/changelog_11.rst
+++ b/doc/build/changelog/changelog_11.rst
@@ -7,16 +7,20 @@
     .. include:: changelog_10.rst
         :start-line: 5
 
+
     .. include:: changelog_09.rst
         :start-line: 5
 
+
     .. include:: changelog_08.rst
         :start-line: 5
 
+
     .. include:: changelog_07.rst
         :start-line: 5
 
 
+
 .. changelog::
     :version: 1.1.19
     :include_notes_from: unreleased_11
diff --git a/doc/build/changelog/migration_08.rst b/doc/build/changelog/migration_08.rst
index 64ef46c26..33cfbba4f 100644
--- a/doc/build/changelog/migration_08.rst
+++ b/doc/build/changelog/migration_08.rst
@@ -1296,7 +1296,7 @@ be no pending state change on an unloaded attribute.
 :ticket:`2320`
 
 :attr:`.Column.key` is honored in the :attr:`.Select.c` attribute of :func:`.select` with :meth:`.Select.apply_labels`
------------------------------------------------------------------------------------------------------------------------
+--------------------------------------------------------------------------------------------------------------------------------
 
 Users of the expression system know that :meth:`.Select.apply_labels`
 prepends the table name to each column name, affecting the
diff --git a/doc/build/core/constraints.rst b/doc/build/core/constraints.rst
index 0415438a0..311b32df3 100644
--- a/doc/build/core/constraints.rst
+++ b/doc/build/core/constraints.rst
@@ -1,7 +1,7 @@
 .. _metadata_constraints_toplevel:
 .. _metadata_constraints:
 
-.. module:: sqlalchemy.schema
+.. currentmodule:: sqlalchemy.schema
 
 ================================
 Defining Constraints and Indexes
diff --git a/doc/build/core/custom_types.rst b/doc/build/core/custom_types.rst
index 1120f04bf..bf6fdbabb 100644
--- a/doc/build/core/custom_types.rst
+++ b/doc/build/core/custom_types.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.types
+.. currentmodule:: sqlalchemy.types
 
 .. _types_custom:
 
diff --git a/doc/build/core/ddl.rst b/doc/build/core/ddl.rst
index db0905d72..38a660982 100644
--- a/doc/build/core/ddl.rst
+++ b/doc/build/core/ddl.rst
@@ -1,6 +1,6 @@
 .. _metadata_ddl_toplevel:
 .. _metadata_ddl:
-.. module:: sqlalchemy.schema
+.. currentmodule:: sqlalchemy.schema
 
 Customizing DDL
 ===============
diff --git a/doc/build/core/defaults.rst b/doc/build/core/defaults.rst
index cbfe27c33..6372e5e54 100644
--- a/doc/build/core/defaults.rst
+++ b/doc/build/core/defaults.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.schema
+.. currentmodule:: sqlalchemy.schema
 
 .. _metadata_defaults_toplevel:
 
diff --git a/doc/build/core/dml.rst b/doc/build/core/dml.rst
index 3b6949b79..51c9a2f1c 100644
--- a/doc/build/core/dml.rst
+++ b/doc/build/core/dml.rst
@@ -5,7 +5,7 @@ INSERT, UPDATE and DELETE statements build on a hierarchy starting
 with :class:`.UpdateBase`.   The :class:`.Insert` and :class:`.Update`
 constructs build on the intermediary :class:`.ValuesBase`.
 
-.. module:: sqlalchemy.sql.expression
+.. currentmodule:: sqlalchemy.sql.expression
 
 .. autofunction:: delete
 
diff --git a/doc/build/core/functions.rst b/doc/build/core/functions.rst
index 90164850d..cb53eda13 100644
--- a/doc/build/core/functions.rst
+++ b/doc/build/core/functions.rst
@@ -5,7 +5,7 @@
 SQL and Generic Functions
 =========================
 
-.. module:: sqlalchemy.sql.expression
+.. currentmodule:: sqlalchemy.sql.expression
 
 SQL functions which are known to SQLAlchemy with regards to database-specific
 rendering, return types and argument behavior. Generic functions are invoked
diff --git a/doc/build/core/reflection.rst b/doc/build/core/reflection.rst
index 55962ebe5..fecca8e30 100644
--- a/doc/build/core/reflection.rst
+++ b/doc/build/core/reflection.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.schema
+.. currentmodule:: sqlalchemy.schema
 
 .. _metadata_reflection_toplevel:
 .. _metadata_reflection:
diff --git a/doc/build/core/schema.rst b/doc/build/core/schema.rst
index 8553ebcbf..5de685c7f 100644
--- a/doc/build/core/schema.rst
+++ b/doc/build/core/schema.rst
@@ -4,7 +4,7 @@
 Schema Definition Language
 ==========================
 
-.. module:: sqlalchemy.schema
+.. currentmodule:: sqlalchemy.schema
 
 This section references SQLAlchemy **schema metadata**, a comprehensive system of describing and inspecting
 database schemas.
diff --git a/doc/build/core/selectable.rst b/doc/build/core/selectable.rst
index 57e389722..8952daec5 100644
--- a/doc/build/core/selectable.rst
+++ b/doc/build/core/selectable.rst
@@ -7,7 +7,7 @@ distinguishing feature is their :attr:`.FromClause.c` attribute, which is
 a namespace of all the columns contained within the FROM clause (these
 elements are themselves :class:`.ColumnElement` subclasses).
 
-.. module:: sqlalchemy.sql.expression
+.. currentmodule:: sqlalchemy.sql.expression
 
 .. autofunction:: alias
 
diff --git a/doc/build/core/sqlelement.rst b/doc/build/core/sqlelement.rst
index bdd2091f6..daf2ada2f 100644
--- a/doc/build/core/sqlelement.rst
+++ b/doc/build/core/sqlelement.rst
@@ -1,7 +1,7 @@
 Column Elements and Expressions
 ===============================
 
-.. module:: sqlalchemy.sql.expression
+.. currentmodule:: sqlalchemy.sql.expression
 
 The expression API consists of a series of classes each of which represents a
 specific lexical element within a SQL string.  Composed together
diff --git a/doc/build/core/type_api.rst b/doc/build/core/type_api.rst
index f165df5a2..115cbd202 100644
--- a/doc/build/core/type_api.rst
+++ b/doc/build/core/type_api.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.types
+.. currentmodule:: sqlalchemy.types
 
 .. _types_api:
 
diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst
index abd969933..10a6f10e5 100644
--- a/doc/build/orm/collections.rst
+++ b/doc/build/orm/collections.rst
@@ -13,7 +13,6 @@ This section presents additional information about collection configuration
 and techniques.
 
 .. _largecollections:
-.. currentmodule:: sqlalchemy.orm
 
 Working with Large Collections
 ==============================
@@ -185,6 +184,7 @@ database.
     :paramref:`.orm.mapper.passive_deletes` - similar feature on :func:`.mapper`
 
 .. currentmodule:: sqlalchemy.orm.collections
+
 .. _custom_collections:
 
 Customizing Collection Access
diff --git a/doc/build/orm/composites.rst b/doc/build/orm/composites.rst
index 5cd86d99a..6b9d857d6 100644
--- a/doc/build/orm/composites.rst
+++ b/doc/build/orm/composites.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 .. _mapper_composite:
 
diff --git a/doc/build/orm/constructors.rst b/doc/build/orm/constructors.rst
index 4d7268557..ded70a972 100644
--- a/doc/build/orm/constructors.rst
+++ b/doc/build/orm/constructors.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 .. _mapping_constructors:
 
diff --git a/doc/build/orm/loading_columns.rst b/doc/build/orm/loading_columns.rst
index afa54078f..693f40e04 100644
--- a/doc/build/orm/loading_columns.rst
+++ b/doc/build/orm/loading_columns.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 ===============
 Loading Columns
diff --git a/doc/build/orm/mapped_attributes.rst b/doc/build/orm/mapped_attributes.rst
index bce40bfb4..535c075c9 100644
--- a/doc/build/orm/mapped_attributes.rst
+++ b/doc/build/orm/mapped_attributes.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 Changing Attribute Behavior
 ===========================
diff --git a/doc/build/orm/mapped_sql_expr.rst b/doc/build/orm/mapped_sql_expr.rst
index b17798d0b..09625f51f 100644
--- a/doc/build/orm/mapped_sql_expr.rst
+++ b/doc/build/orm/mapped_sql_expr.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 .. _mapper_sql_expressions:
 
diff --git a/doc/build/orm/mapping_api.rst b/doc/build/orm/mapping_api.rst
index cd7c379cd..99e0ba52d 100644
--- a/doc/build/orm/mapping_api.rst
+++ b/doc/build/orm/mapping_api.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 Class Mapping API
 =================
diff --git a/doc/build/orm/mapping_columns.rst b/doc/build/orm/mapping_columns.rst
index 7d7b69140..71e145747 100644
--- a/doc/build/orm/mapping_columns.rst
+++ b/doc/build/orm/mapping_columns.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 Mapping Table Columns
 =====================
diff --git a/doc/build/orm/query.rst b/doc/build/orm/query.rst
index a192bad94..e997a4dcb 100644
--- a/doc/build/orm/query.rst
+++ b/doc/build/orm/query.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 .. _query_api_toplevel:
 
diff --git a/doc/build/orm/relationship_api.rst b/doc/build/orm/relationship_api.rst
index 03045f698..2766c4020 100644
--- a/doc/build/orm/relationship_api.rst
+++ b/doc/build/orm/relationship_api.rst
@@ -1,4 +1,4 @@
-.. automodule:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 Relationships API
 -----------------
diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst
index f5cbac87e..37f59d345 100644
--- a/doc/build/orm/relationships.rst
+++ b/doc/build/orm/relationships.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 .. _relationship_config_toplevel:
 
diff --git a/doc/build/orm/scalar_mapping.rst b/doc/build/orm/scalar_mapping.rst
index 65efd5dbd..e8829af49 100644
--- a/doc/build/orm/scalar_mapping.rst
+++ b/doc/build/orm/scalar_mapping.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
 
 ===============================
 Mapping Columns and Expressions
diff --git a/doc/build/orm/session_api.rst b/doc/build/orm/session_api.rst
index 8b1ba660f..041ebc0a1 100644
--- a/doc/build/orm/session_api.rst
+++ b/doc/build/orm/session_api.rst
@@ -1,4 +1,4 @@
-.. module:: sqlalchemy.orm.session
+.. currentmodule:: sqlalchemy.orm.session
 
 Session API
 ===========
diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py
index a6a85c60f..7de1b9807 100644
--- a/lib/sqlalchemy/sql/base.py
+++ b/lib/sqlalchemy/sql/base.py
@@ -375,7 +375,9 @@ class Executable(Generative):
         self._execution_options = self._execution_options.union(kw)
 
     def execute(self, *multiparams, **params):
-        """Compile and execute this :class:`.Executable`."""
+        """Compile and execute this :class:`.Executable`.
+
+        """
         e = self.bind
         if e is None:
             label = getattr(self, 'description', self.__class__.__name__)