Allow the mysql mode to be more than just TRADITIONAL

To make it easier to later move to oslo.db match there ability
to set a different mysql mode (this will default, unless configured
explicitly off/differently to TRADITIONAL).

To ensure that we retain backwards compatibility the prior existence
of 'mysql_traditional_mode' as a boolean option will by default set
the mode to TRADITIONAL, and a new configuration option 'mysql_sql_mode' can
be used to provide a secondary overriding mode that will be used
instead (incase someone wants to use something other than TRADITIONAL).

Closes-Bug: 1326568

Change-Id: Ide34c27b12c26030c8842f3f4b0fcca43ce783a7
Include the function name on internal errors

To make it easier to debug and reason about the
exception that occurred include the function name
that was called during the sessions activation in
the exception message (and associated LOG output).

Change-Id: I21f9310f78968d1e60d88b1f77be0dc629e75525
Create a considerations section

Instead of having the considerations and best practices that
should be used when developing with this library scattered
across a few different links and pages combine these together
into a single section in the developer documentation. As a
side-effect of this change remove the documenation about the
utils to use and not use and just refer those to use the modules,
classes and APIs described in these documents.

Change-Id: I20e1405cb6ecb654baa29812b98ada7bdc393f6c
Switch to a restructuredtext README file

To make the README file showup in a more readable manner
on pypi and on other external sites convert the README from
the markdown format and move it to the restructuredtext format
which displays better on those external sites (and keeps our
documentation consistently one format).

Change-Id: I38f7152c264bbc0ebcf4a539b36f8b21e86705b8
Merge "Switch to a restructuredtext README file"
Merge "Allow the mysql mode to be more than just TRADITIONAL"
Merge "Include the function name on internal errors"
Merge "Create a considerations section"