hv.output help is confusing

[jbednar]

hv.help(hv,.output) doesn't print anything useful at all, and help(hv.output) (a) doesn't show the docstring for the actual output function, and (b) seems to be about display, not output:

>>> import holoviews as hv
>>> hv.help(hv.output)
Parameters of 'output'
======================

Object has no parameters.
>>> help(hv.output)
Help on class output in module holoviews.util:

class output(param.parameterized.ParameterizedFunction)
 |  output(*args, **params)
 |  
 |  output(backend=None, fig=None, holomap=None, widgets=None, fps=None, max_frames=None, size=None, dpi=None, filename=None, info=None, css=None)
 |  
 |  Helper used to set HoloViews display options.
 |  Arguments are supplied as a series of keywords in any order:
...

There is useful info in the output docstring, but it doesn't seem to appear anywhere:

class output(param.ParameterizedFunction):
    """
    Utility function to set output either at the global level or on a
    specific object.

    To set output globally use:

    output(options)

    Where options may be an options specification string (as accepted by
    the IPython opts magic) or an options specifications dictionary.

    For instance:

    output("backend='bokeh'") # Or equivalently
    output(backend='bokeh')

    To set save output from a specific object do disk using the
    'filename' argument, you can supply the object as the first
    positional argument and supply the filename keyword:

    curve = hv.Curve([1,2,3])
    output(curve, filename='curve.png')

    For compatibility with the output magic, you can supply the object
    as the second argument after the string specification:

    curve = hv.Curve([1,2,3])
    output("filename='curve.png'", curve)

    These two modes are equivalent to the IPython output line magic and
    the cell magic respectively.

[jlstevens]

Moving the docstring from the class level to the __call__ method should do the trick.

[jbednar]

From the source code, yes, any class docstring will be overwritten by output.__doc__ = Store.output_settings._generate_docstring(), so indeed the docstring does need to move to __call__. But even after doing that, the docstring is only available using help(hv.output.__call__); it still doesn't show up for hv.help(hv.output). So this human-written docstring doesn't seem to be used in any reasonable way, as it's almost impossible to read the result from help(output).

I propose that the class docstring should be printed for hv.help(Parameterized(...), and the __call__ docstring should be printed for hv.help(ParameterizedFunction).