Improve the display of docstrings

[crwilcox]

In a recent post to HN about PTVS we received feedback that our documentation could be much easier to read. The thought here is to provide a better format, more full documentation experience for our users.
#235 captures the improvements to parsing to bring in missing docstrings.

This issue captures displaying those docstrings better.

Particularly there are two things to be addressed here

1. We need to simply display more content
2. We can improve the formatting of the displayed content to not just be a, more or less, printout of the docstring

The success of this work item will depend on the implementation of #235 to some extent as it will assist in completing item number 1.

Here is what we display for this method. Below it is the full docstring. We need to display more of this. (Item 1)

def example_generator(n):
    """Generators have a ``Yields`` section instead of a ``Returns`` section.

    Args:
        n (int): The upper limit of the range to generate, from 0 to `n` - 1.

    Yields:
        int: The next number in the range of 0 to `n` - 1.

    Examples:
        Examples should be written in doctest format, and should illustrate how
        to use the function.

        >>> print([i for i in example_generator(4)])
        [0, 1, 2, 3]

    """
    for i in range(n):
        yield i

Here is an image of the Documentaion Display brought up by 'ctrl+space' currently

We could add color or boldness, format better, etc.
A sort of thought on the above is making it look like the following:

Or with color as well for certain '' and ' fields

Inspiration from HN Comments: (https://news.ycombinator.com/item?id=9998227, user saboot)

• Reading intellisense python documentation in the mouse over window is really tedious. There is an object window that can display documentation for your classes, but not from libraries.
• Rendered docs are much easier to read. Spyder did this very well. With PTVS I'm looking at the docs online for numpy and matplotlib. With spyder I just ctrl+I and it displays using sphinx very nicely.

[zooba]

We should be able to display more content now, since the bug that used to be in VS limiting the height of the tooltip is fixed.

Colours in tooltips is a big risk, as the tooltips are themed, but if we can find an easy way to tie them to the editor colours when we generate the XAML for them we should be okay. What might be easier is having an object browser for our analysed results that F12 (or maybe we steal F1?) can open - more like how Jupyter does its ? and ?? support. Then we could use an actual editor window to render the documentation. If we enable Alt+F12 (peek definition) and colourisation for doc comments then we get basically all of this anyway.

#235 and #773 will also help display more accurate information in completion lists.

[den-run-ai]

+1, and scrollable tooltip docstring information

[zooba]

Scrollable would be amazing, but I don't think it's technically feasible due to the way those tooltips are implemented. (Though I heard there were some changed made for VS 2015, so that may no longer be the case. Fairly sure it still can't get though focus, which makes scrolling impossible.)

[KhaoticMind]

I agree with @crwilcox. I'm used to Spyder and Ctrl+I to see the whole documentation for Numpy, Scikit-learn and the likes is one feature I'm missing in PTVS.

I also think a dedicated window to browse the documentation would be the way better than tooltips for two reasons:

1. Scientific libs docs are way larger then regular ones;
2. Sometimes I want to keep the doc open and code, to make sure I get the meaning/options of the parameters right;

Here is how Spyder does it: https://pythonhosted.org/spyder/inspector.html