From d56887bcb63808ff6b42e4370ec082a8ef5a41a0 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sat, 11 Apr 2020 13:53:41 -0400 Subject: [PATCH] Fix almost all read-level sphinx warnings Partial backport of 43bcb0de1ecc1dc2abd7e7c3eb0c39f3eab9adc0. Also enables sphinx multiprocess. Change-Id: I49b1959b9a5fe84fb4c74366da2724284a804936 --- doc/build/Makefile | 2 +- doc/build/changelog/changelog_07.rst | 34 ++++++++++++++-------------- doc/build/changelog/changelog_08.rst | 1 - doc/build/changelog/changelog_09.rst | 2 ++ doc/build/changelog/changelog_10.rst | 5 ++-- doc/build/changelog/changelog_11.rst | 4 ++++ doc/build/changelog/changelog_12.rst | 2 ++ doc/build/changelog/migration_08.rst | 2 +- doc/build/core/constraints.rst | 2 +- doc/build/core/custom_types.rst | 2 +- doc/build/core/ddl.rst | 2 +- doc/build/core/defaults.rst | 2 +- doc/build/core/dml.rst | 2 +- doc/build/core/functions.rst | 2 +- doc/build/core/reflection.rst | 2 +- doc/build/core/schema.rst | 2 +- doc/build/core/selectable.rst | 2 +- doc/build/core/sqlelement.rst | 2 +- doc/build/core/type_api.rst | 2 +- doc/build/orm/collections.rst | 2 +- doc/build/orm/composites.rst | 2 +- doc/build/orm/constructors.rst | 2 +- doc/build/orm/loading_columns.rst | 2 +- doc/build/orm/mapped_attributes.rst | 2 +- doc/build/orm/mapped_sql_expr.rst | 2 +- doc/build/orm/mapping_api.rst | 2 +- doc/build/orm/mapping_columns.rst | 2 +- doc/build/orm/query.rst | 2 +- doc/build/orm/relationship_api.rst | 2 +- doc/build/orm/relationships.rst | 2 +- doc/build/orm/scalar_mapping.rst | 2 +- doc/build/orm/session_api.rst | 2 +- lib/sqlalchemy/sql/base.py | 4 +++- lib/sqlalchemy/util/langhelpers.py | 4 +++- 34 files changed, 60 insertions(+), 48 deletions(-) diff --git a/doc/build/Makefile b/doc/build/Makefile index cd39b72888..58fdc6c162 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 2ddeedded2..f921d29491 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 bef1ece84c..e50b140ac6 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 a3140f0ca1..ad8a901678 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 7126bfcbe9..3437b74f4d 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 0ba89e7514..aec6670388 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/changelog_12.rst b/doc/build/changelog/changelog_12.rst index 66a4677808..d7eece95c9 100644 --- a/doc/build/changelog/changelog_12.rst +++ b/doc/build/changelog/changelog_12.rst @@ -7,9 +7,11 @@ .. include:: changelog_11.rst :start-line: 5 + .. include:: changelog_10.rst :start-line: 5 + .. changelog:: :version: 1.2.20 :include_notes_from: unreleased_12 diff --git a/doc/build/changelog/migration_08.rst b/doc/build/changelog/migration_08.rst index dcf117c294..f0661c4fc1 100644 --- a/doc/build/changelog/migration_08.rst +++ b/doc/build/changelog/migration_08.rst @@ -1298,7 +1298,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 991820efca..c077cd8377 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 b7d0eef936..02b2a500fe 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 3ca4dccf48..46a4e1d841 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 6775f31551..07f859001c 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 3b6949b795..51c9a2f1cd 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 90164850d4..cb53eda139 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 8092f14906..1848c044e0 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 8553ebcbf6..5de685c7f2 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 57e389722e..8952daec5e 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 bdd2091f61..daf2ada2f6 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 f165df5a26..115cbd202f 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 9e49f7c1ea..cba82ef00d 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 e933e81c90..786a6b5be8 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 4d7268557d..ded70a9720 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 d128651453..5135dff64f 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 bce40bfb49..535c075c94 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 e04abba806..db3b84b7c9 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 cd7c379cd2..99e0ba52d4 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 7d7b691409..71e145747c 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 a192bad941..e997a4dcbd 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 03045f6980..2766c4020a 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 f5cbac87eb..37f59d3452 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 65efd5dbd9..e8829af49a 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 683719945f..11e37a2c87 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 4259cecb4b..d67fba2905 100644 --- a/lib/sqlalchemy/sql/base.py +++ b/lib/sqlalchemy/sql/base.py @@ -401,7 +401,9 @@ class Executable(Generative): return self._execution_options 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__) diff --git a/lib/sqlalchemy/util/langhelpers.py b/lib/sqlalchemy/util/langhelpers.py index f2341222c1..876a4bd713 100644 --- a/lib/sqlalchemy/util/langhelpers.py +++ b/lib/sqlalchemy/util/langhelpers.py @@ -213,7 +213,7 @@ def %(name)s(%(args)s): "Inherited from :func:`sqlalchemy%s`; this constructor " "creates a :class:`%s` object" % (linked_to_location, class_location), - 0, + 1, ) decorated.__doc__ = linked_to_doc else: @@ -1677,6 +1677,8 @@ def _dedent_docstring(text): def inject_docstring_text(doctext, injecttext, pos): doctext = _dedent_docstring(doctext or "") lines = doctext.split("\n") + if len(lines) == 1: + lines.append("") injectlines = textwrap.dedent(injecttext).split("\n") if injectlines[0]: injectlines.insert(0, "") -- 2.47.2