Cleanups and documentation related to deprecation

Correct Sphinx docs for deprecated features and use the new @deprecated in pypo.

Added to the syleguide notes on using ``.. deprecated``