port and update documentation w.r.t. deprecated functionality

renndered version available at http://boegel-eb.readthedocs.org/en/deprecated/Deprecated-functionality.html
that should be 
```
``log.deprecated(message, "X.Y")``
```