Set return of type Axes in Numpydoc docstring return type hint for Figure.add_subplot and Figure.add_axes to help jedi introspection

[bcolsen]

I've noticed there is push in the documentation for using objects over the pyplot functions. I agree that this the best way to use Matplotlib(other than the set_ get_ methods). The problem I have is that Jedi(used in Spyder IDE and other editors) doesn't recognize the return types of some Matplotlib functions and methods such as plt.figure and plt.subplot. For example in Jedi 0.9 you get:

In [1]: import jedi; jedi.Script('import pylab; a = pylab.figure(); a.set_f').completions()
Out[1]: []

I usually have to play with MPL code in the console first to remember all the functions instead of just typing it all in the editor.

Luckily recently this patch(davidhalter/jedi#796) has been recently submitted to Jedi(not by me) which adds among other things implements return type hints from numpydoc docstrings. With this Jedi patch I get:

In [1]: import jedi; jedi.Script('import pylab; a = pylab.figure(); a.set_f').completions()
Out[1]: 
[<Completion: set_facecolor>,
 <Completion: set_figheight>,
 <Completion: set_figure>,
 <Completion: set_figwidth>,
 <Completion: set_frameon>]

Which is great. This works because there is a Numpydoc docstring for plt.figure with return of Figure. This works in Spyder IDE as well.

Unfortunately, this code doesn't work even after the patch:

import jedi; jedi.Script('import pylab; ax = pylab.figure().add_subplot(111); ax.set_x').completions()

This is a result of the docstrings for Figure.add_subplot and Figure.add_axes not containing a numpydoc return statement.

However, If I add this the top of their docstrings:

    """
    Returns
    -------
    axes : Axes
       The Axes you made
       
    Examples
    --------

I then get this result with the patch applied:

In [3]: import jedi; jedi.Script('import pylab; ax = pylab.figure().add_subplot(111); ax.set_x').completions()
Out[3]: 
[<Completion: set_xbound>,
 <Completion: set_xlabel>,
 <Completion: set_xlim>,
 <Completion: set_xmargin>,
 <Completion: set_xscale>,
 <Completion: set_xticklabels>,
 <Completion: set_xticks>]

Which is quite helpful when trying to remember all those Axes methods and for new learners.

I'm sure there are a few other functions( like plt.gcf and Figure.gca to name a couple) that could use a type hint as well.

Here it is working in Spyder (Some functions of Numpy work too...That z completes as a numpy.adarray ):

For more info on this with spyder see my comments on spyder-ide/spyder#2162

To help us understand and resolve your issue please check that you have provided
the information below.

• Matplotlib version, Python version and Platform (Windows, OSX, Linux ...)
  I'm using Python 3.5 on Linux with Matplotlib 1.5.3
• How did you install Matplotlib and Python (pip, anaconda, from source ...)
  Anaconda
• If possible please supply a Short, Self Contained, Correct, Example
  that demonstrates the issue i.e a small piece of code which reproduces the issue
  and can be run with out any other (or as few as possible) external dependencies.
• If this is an image generation bug attach a screenshot demonstrating the issue.
• If this is a regression (Used to work in an earlier version of Matplotlib), please
  note where it used to work.

[QuLogic]

This is basically just another reason to complete #7205, so I'm going to close this one as sort-of-duplicate. I added the two methods to the list there (though eventually everything should be done.)