clean up signal docs

fix py3 print in doc config

Author: davidism

docs/conf.py

@@ -51,10 +51,10 @@
 try:
     release = pkg_resources.get_distribution('Flask-SQLAlchemy').version
 except pkg_resources.DistributionNotFound:
-    print 'To build the documentation, The distribution information of'
-    print 'Flask-SQLAlchemy has to be available.  Either install the package'
-    print 'into your development environment or run "setup.py develop"'
-    print 'to setup the metadata.  A virtualenv is recommended!'
+    print('To build the documentation, The distribution information of')
+    print('Flask-SQLAlchemy has to be available.  Either install the package')
+    print('into your development environment or run "setup.py develop"')
+    print('to setup the metadata.  A virtualenv is recommended!')
     sys.exit(1)
 del pkg_resources
 
@@ -232,13 +232,13 @@
 # fall back if theme is not there
 try:
     __import__('flask_theme_support')
-except ImportError, e:
-    print '-' * 74
-    print 'Warning: Flask themes unavailable.  Building with default theme'
-    print 'If you want the Flask themes, run this command and build again:'
-    print
-    print '  git submodule update --init'
-    print '-' * 74
+except ImportError as e:
+    print('-' * 74)
+    print('Warning: Flask themes unavailable.  Building with default theme')
+    print('If you want the Flask themes, run this command and build again:')
+    print()
+    print('  git submodule update --init')
+    print('-' * 74)
 
     pygments_style = 'tango'
     html_theme = 'default'

docs/config.rst

@@ -53,11 +53,13 @@ A list of configuration keys currently understood by the extension:
                                    its maximum size.  When those additional
                                    connections are returned to the pool,
                                    they are disconnected and discarded.
-``SQLALCHEMY_TRACK_MODIFICATIONS`` If set to `True` (the default)
-                                   Flask-SQLAlchemy will track
-                                   modifications of objects and emit
-                                   signals.  This requires extra memory
-                                   and can be disabled if not needed. 
+``SQLALCHEMY_TRACK_MODIFICATIONS`` If set to ``True``, Flask-SQLAlchemy will
+                                   track modifications of objects and emit
+                                   signals.  The default is ``None``, which
+                                   enables tracking but issues a warning
+                                   that it will be disabled by default in
+                                   the future.  This requires extra memory
+                                   and should be disabled if not needed.
 ================================== =========================================
 
 .. versionadded:: 0.8
@@ -73,6 +75,8 @@ A list of configuration keys currently understood by the extension:
 
 .. versionadded:: 2.0
    The ``SQLALCHEMY_TRACK_MODIFICATIONS`` configuration key was added.
+.. versionchanged:: 2.1
+   ``SQLALCHEMY_TRACK_MODIFICATIONS`` will warn if unset.
 
 Connection URI Format
 ---------------------

docs/signals.rst

@@ -1,27 +1,24 @@
 Signalling Support
 ==================
 
-.. versionadded:: 0.10
-
-Starting with Flask-SQLAlchemy 0.10 you can now connect to signals to get
-notifications when certain things happen.
+Connect to the following signals to get notified before and after changes are committed to the database.
+These changes are only tracked if ``SQLALCHEMY_TRACK_MODIFICATIONS`` is enabled in the config.
 
-The following two signals exist:
+.. versionadded:: 0.10
+.. versionchanged:: 2.1
+   ``before_models_committed`` is triggered correctly.
+.. deprecated:: 2.1
+   This will be disabled by default in a future version.
 
 .. data:: models_committed
 
-   This signal is sent when changed models were committed to the
-   database.  The sender is the application that emitted the changes
-   and the models and an operation identifier are passed as list of tuples
-   in the form ``(model, operation)`` to the receiver in the `changes`
-   parameter.
+   This signal is sent when changed models were committed to the database.
+
+   The sender is the application that emitted the changes.
+   The receiver is passed the ``changes`` parameter with a list of tuples in the form ``(model instance, operation)``.
 
-   The model is the instance of the model that was sent to the database
-   and the operation is ``'insert'`` when a model was inserted,
-   ``'delete'`` when the model was deleted and ``'update'`` if any
-   of the columns where updated.
+   The operation is one of ``'insert'``, ``'update'``, and ``'delete'``.
 
 .. data:: before_models_committed
 
-   Works exactly the same as :data:`models_committed` but is emitted
-   right before the committing takes place.
+   This signal works exactly like :data:`models_committed` but is emitted before the commit takes place.