[docs] Documentation Patch: Deprecations first

[Tony R.]

SUMMARY
========

If a class, or a function, or *anything* is deprecated, I think the deprecation should be the first thing in the description.



Rationale
-----------

When preparing to use a module for the first time, I have often read through long, detailed documentation, only to discover that the subject of my attention was deprecated.  It would save time and frustration for the reader to have the deprecation notice at the beginning of the description, rather than the end.  

Often, deprecations include a message like “[spam] is deprecated; use [eggs] instead”.  Even better!  Now the reader can do better than saving themselves the time they would have wasted reading the description; they can go directly to the intended replacement for the deprecated item.



Patch
-------

Attached is a patch that contains the modifications to the *.rst docs.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: docs-deprecations-first.diff
Type: application/octet-stream
Size: 46674 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/docs/attachments/20150918/84f53350/attachment-0001.obj>
-------------- next part --------------