Improvements to the location of the return type

[hoodmane]

The current strategy to place the rtype is still not fully satisfactory on my own documentation. I think this improves it to avoid any need for fudging.

1. If there is an existing :rtype: don't add another
2. If there is a :returns: anywhere, either add directly before it or modify the :returns: line as appropriate
3. If there is a block of :param: documentation, add directly after this
4. If there is a .. directive, add before the directive
5. Add at the end

Step 4 could be refined further, we would really only like to break at directives that introduce headings.

Since it is very hard to decide where the :param: block ends based on directly analyzing the text so I parse the docstring into a docutils tree. From the tree it is not too hard to work out what we need to know.