Documentation on transactions and threading.

This adds documentatuon on transactions and threading concerns.

There are some topics, like application design and conflict resolution
that might want a deeper treatment, but would probably be better
handled through articles or dedicated topics. (I want to avoid
individual topics being too long or weedy to read, where practical.)

Writing this, I stumbled a bit over thread-local transaction managers.
For most applications, they don't add anything over accessing
transaction managers on connections and actually provide an
opportunity to fail. I'm convinced that it should be possible to do
most transaction management through connections and that the API
provided by transaction managers and the transaction package should be
reserved for distributed transactions.

I didn't mention gevent. I thik there should be a section on gevent,
but I think it should be written by someone who's used gevent with
ZODB. :)

Maybe there should also be a section or mention of using asyncio with
ZODB, pr maybe later.

Closes zopefoundation/zodbdocs#13
Closes zopefoundation/zodbdocs#16

CHANGES.rst

@@ -2,7 +2,7 @@
  Change History
 ================
 
-5.0.1 (unreleased)
+5.0.1 (2016-09-09)
 ==================
 
 - Fix an AttributeError that DemoStorage could raise if it was asked
@@ -12,6 +12,8 @@
 - Call _p_resolveConflict() even if a conflicting change doesn't change the
   state. This reverts to the behaviour of 3.10.3 and older.
 
+- Many docstrings have been improved.
+
 5.0.0 (2016-09-06)
 ==================
 

doc/articles/old-guide/prog-zodb.rst

@@ -435,7 +435,7 @@ new schema.  This can be easy if your network of object references is quite
 structured, making it easy to find all the instances of the class being
 modified.  For example, if all :class:`User` objects can be found inside a
 single dictionary or BTree, then it would be a simple matter to loop over every
-:class:`User` instance with a :keyword:`for` statement. This is more difficult
+:class:`User` instance with a ``for`` statement. This is more difficult
 if your object graph is less structured; if :class:`User` objects can be found
 as attributes of any number of different class instances, then there's no longer
 any easy way to find them all, short of writing a generalized object traversal

doc/guide/index.rst

@@ -14,13 +14,11 @@ If you haven't yet, you should read the :ref:`Tutorial <tutorial-label>`.
 
    install-and-run
    writing-persistent-objects.rst
+   transactions-and-threading
 
 .. todo:
 
-   transaction.rst
-   storages.rst
-   configuration.rst
-   threading.rst
-   packing-and-garbage-collection.rst
-   blobs.rst
-   multi-databases.rst
+   blobs
+   packing-and-garbage-collection
+   multi-databases
+   blobs

doc/guide/install-and-run.rst

@@ -128,6 +128,8 @@ much of anything.  Connections take care of loading and saving objects
 and manage object caches. Each connection has it's own cache
 [#caches-are-expensive]_.
 
+.. _getting-connections:
+
 Getting connections
 -------------------
 
@@ -144,7 +146,7 @@ db.open()
    done using the connection.
 
    If changes are made, the application :ref:`commits transactions
-   <commit-transactions>` to make them permanent.
+   <using-transactions-label>` to make them permanent.
 
 db.transaction()
    The database :meth:`~ZODB.DB.transaction` method

doc/reference/index.rst

@@ -6,6 +6,6 @@ Reference Documentation
 .. toctree::
    :maxdepth: 2
 
-   zodb.rst
-   storages.rst
- 
+   zodb
+   storages
+   transaction

doc/reference/transaction.rst

+============
+Transactions
+============
+
+Transaction support is provided by the `transaction
+<http://transaction.readthedocs.io/en/latest/>`_ package, which is
+installed automatically when you install ZODB.  There are 2 important
+APIs provided by the transaction package, ``ITransactionManager`` and
+``ITransaction``, described below.
+
+ITransactionManager
+===================
+
+.. autointerface:: transaction.interfaces.ITransactionManager
+   :members: begin, get, commit, abort, doom, isDoomed, savepoint
+
+ITransaction
+============
+
+.. autointerface:: transaction.interfaces.ITransaction
+   :members: user, description, commit, abort, doom, savepoint, note,
+             setUser, setExtendedInfo,
+             addBeforeCommitHook, getBeforeCommitHooks,
+             addAfterCommitHook, getAfterCommitHooks
+

doc/reference/zodb.rst

@@ -84,7 +84,8 @@ Connections
 .. autoclass:: ZODB.Connection.Connection
    :members: add, cacheGC, cacheMinimize, close, db, get,
              getDebugInfo, get_connection, isReadOnly, oldstate,
-             onCloseCallback, root, setDebugInfo, sync
+             onCloseCallback, root, setDebugInfo, sync,
+             transaction_manager
 
 TimeStamp (transaction ids)
 ===========================

src/ZODB/Connection.py

@@ -50,6 +50,8 @@ import six
 
 from .mvccadapter import HistoricalStorageAdapter
 
+from . import valuedoc
+
 global_reset_counter = 0
 
 noop = lambda : None
@@ -88,6 +90,9 @@ class Connection(ExportImport, object):
 
     _code_timestamp = 0
 
+    #: Transaction manager associated with the connection when it was opened.
+    transaction_manager = valuedoc.ValueDoc('current transaction manager')
+
     ##########################################################################
     # Connection methods, ZODB.IConnection
 

src/ZODB/tests/testdocumentation.py

@@ -43,6 +43,7 @@ def test_suite():
             manuel.doctest.Manuel() + manuel.capture.Manuel(),
             join(guide, 'writing-persistent-objects.rst'),
             join(guide, 'install-and-run.rst'),
+            join(guide, 'transactions-and-threading.rst'),
             join(reference, 'zodb.rst'),
             join(reference, 'storages.rst'),
             setUp=setUp, tearDown=tearDown,