Skip to content

Documentation in the help pannel from IPython is more complete than from the editor #5522

Open

Description

@bcolsen

Description of your problem

Matplotlib documentation in the help(ctrl-i) from IPython is more complete than help(ctrl-i) from the editor. I noticed this from #5514

What steps will reproduce the problem?

  1. Type in to the editor:
import matplotlib.pyplot as plt
plt.plot
  1. With the cursor on plot press ctrl-i
  2. See this in the help widget:
Definition : plot(*args, **kwargs)
Type : Present in matplotlib.pyplot module
No further documentation available

Not overly helpful.

What is the expected output? What do you see instead?

When I do the same in IPython I get:

Definition : plot(*args, **kwargs)
Type : Function of matplotlib.pyplot module
Plot lines and/or markers to the Axes. args is a variable length argument, allowing for multiple x, y pairs with an optional format string. For example, each of the following is legal:

plot(x, y)        # plot x and y using default line style and color
plot(x, y, 'bo')  # plot x and y using blue circle markers
plot(y)           # plot y using x as index array 0..N-1
plot(y, 'r+')     # ditto, but with red plusses
If x and/or y is 2-dimensional, then the corresponding columns will be plotted.

If used with labeled data, make sure that the color spec is not included as an element in data, as otherwise the last case plot("v","r", data={"v":..., "r":...) can be interpreted as the first case which would do plot(v, r) using the default line style and color.

If not used with labeled data (i.e., without a data argument), an arbitrary number of x, y, fmt groups can be specified, as in:

a.plot(x1, y1, 'g^', x2, y2, 'g-')
Return value is a list of lines that were added.
............

plus more

Please provide any additional information below

I didn't submit this before, because I thought the docs were just not so good, but if IPython can pull better docs then maybe editor can too.

Whenever I show off spyder to people often they try help with matplotlib and the results are not alway helpful.

Versions and main components

  • Spyder Version: 3.2.4
  • Python Version: 3.6.3
  • Qt Version: 5.6.2
  • PyQt Version: 5.6
  • Operating system: Ubuntu 16.04 64-bit

Dependencies

IPython >=4.0 : 6.1.0 (OK)
cython >=0.21 : 0.26.1 (OK)
jedi >=0.9.0 : 0.10.2 (OK)
nbconvert >=4.0 : 5.3.1 (OK)
numpy >=1.7 : 1.12.1 (OK)
pandas >=0.13.1 : 0.20.3 (OK)
psutil >=0.3 : 5.4.0 (OK)
pycodestyle >=2.3: 2.3.1 (OK)
pyflakes >=0.6.0 : 1.6.0 (OK)
pygments >=2.0 : 2.2.0 (OK)
pylint >=0.25 : 1.7.4 (OK)
qtconsole >=4.2.0: 4.3.1 (OK)
rope >=0.9.4 : 0.10.5 (OK)
sphinx >=0.6.6 : 1.6.3 (OK)
sympy >=0.7.3 : 1.1.1 (OK)

Activity

  1. ccordoba12 commented on Oct 23, 2017

    @ccordoba12
    Member

    I think this is fixed in Matplotlib 2.1, because in its release notes they mention that they did a great overhaul of docstrings in that release.

    @bcolsen, could you update to that version and try again? Thanks!

  2. bcolsen commented on Oct 23, 2017

    @bcolsen
    MemberAuthor

    Matplotlib 2.1 didn't help this case. I did, however, reproduce #5514 on my laptop.

    I think matplotlib is using doc producing functions that are not being ran when the editor retrieves the docs (using rope? Edit: it seem to be Jedi)

  3. bcolsen commented on Oct 23, 2017

    @bcolsen
    MemberAuthor

    If it's Jedi I don't think that it can be fixed through Jedi because Jedi won't run any code.

  4. bcolsen commented on Oct 23, 2017

    @bcolsen
    MemberAuthor

    Unfortunately, it seem that the most of the pyplot functions only link to the documentation of the underling function using a decorator.

  5. added this to the v3.2.5 milestone on Oct 23, 2017
  6. self-assigned this
    on Nov 6, 2017
  7. modified the milestones: v3.2.5, v3.2.6 on Dec 6, 2017
  8. modified the milestones: v3.2.6, v3.2.7 on Dec 29, 2017
  9. modified the milestones: v3.2.7, v3.2.8 on Jan 8, 2018
  10. removed this from the v3.2.8 milestone on Mar 3, 2018
  11. 10 remaining items

  12. added this to the important milestone on Feb 24, 2019
  13. bcolsen commented on Mar 11, 2019

    @bcolsen
    MemberAuthor

    From #8915: There is no documentation at all for some Pandas functions including the pd.read_ functions.

  14. changed the title [-]Matplotlib help from IPython is more complete than help from the editor[/-] [+]Documentation in the help pannel from IPython is more complete than from the editor[/+] on Apr 8, 2019
  15. gerazov commented on Apr 9, 2019

    @gerazov

    👍 This would be really nice to have - I use Spyder for teaching and exams, so it's important for students to be able to access Matplotlib's help with ctrl-i.

    The issue with Matplotlib is that pyplot actually comprises wrapper functions meant for interactive plotting around matplotlib’s object-oriented library, i.e. plt.plot actually calls matplotlib.axes.Axes.plot on the current axes. So, as expected, pressing ctr-i on the matplotlib.axes.Axes.plot object in the Editor does work and prints out the whole docstring in the Help window 😄

    @bcolsen I also assumed that it's a problem with the docs, and just found out by accident that plt.plot? in IPython prints an actual docstring which led me to this thread. Doing ctrl-i from IPython is a good workaround for now - thanks for the tip!

  16. bcolsen commented on Apr 10, 2019

    @bcolsen
    MemberAuthor

    Doing ctrl-i from IPython is a good workaround for now - thanks for the tip!

    I'm often doing that myself!

    The real solution to this problem would likely be making a language server for the IPython console.

    We could run ctrl-i on both the editor and the console and compare them but I can't think of a good way of comparing the results.

  17. gerazov commented on Apr 10, 2019

    @gerazov

    Lengthwise comparison should do no? Or just search for

    No further documentation available

    I guess ...

    I don't know how ctrl-i works under the hood but it seems that what can be done is fetch the docstring from the linked function. All of the pyplot functions have decorators for the docstring, e.g. the source code for plot starts with:

    # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
    @_autogen_docstring(Axes.plot)
    def plot(*args, **kwargs):
    ...

    Where the _autogen_docstring function is defined in pyplot as:

    def _autogen_docstring(base):
        """Autogenerated wrappers will get their docstring from a base function
        with an addendum."""
        msg = ''
        addendum = docstring.Appender(msg, '\n\n')
        return lambda func: addendum(docstring.copy_dedent(base)(func))

    This relies on their doctring module which boils down to copying the base function's docstring to the target function's one with:

    def copy(source):
        "Copy a docstring from another source function (if present)"
        def do_copy(target):
            if source.__doc__:
                target.__doc__ = source.__doc__
            return target
        return do_copy

    So, I guess if your print out func.__doc__ with ctrl-i it should work? Namely if I run

    print(plt.plot.__doc__)

    in IPython I get the docstring. This is probably what you already do, so I dunno where things go wrong ...

  18. bcolsen commented on Apr 10, 2019

    @bcolsen
    MemberAuthor

    One solution that might work well is to make a kernel running that imports all the usual packages as their common aliases and when the editor asks for the documentation we compare the docs on the preloaded kernel to the editor.

  19. modified the milestones: v4.0rc, on Sep 15, 2019
  20. removed this from the milestone on Feb 23, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions