python packagisation: Remove misleading "For backward compat" comments

`stbt.get_config` is still the official public API. Splitting stbt.py
into a python package with sub-packages is --so far-- purely an internal
organisation / tidiness exercise.
python packagisation: List stbt public API in __all__
python packagisation: Take APIs to document from stbt.__all__

Instead of maintaining the list in 2 places. The documentation is now
sorted alphabetically instead of thematically, but I think that's
appropriate for reference documentation -- the man page isn't a tutorial.

I had to add a docstring to `ConfigurationError` so that it would
display correctly in the generated file.
Merge pull request #218 from drothlis/python-package-2

Some minor enhancements missing from 8ae1c0c4.