Make Holoviews docstrings meaningful for users

Request

Add docstrings that can help inform the user and ease the learning curve.

Motivation

I am a user of Panel and sometimes HoloViews. I have a very hard time understanding HoloViews. It might be my own fault as I might be able to study the documentation. But that is not the way I work. I am working in my editor VS Code and use the intelligense/ tooltips and tab completion. I expect to have useful information available in my editor.

I find HoloViews very, very difficult to understand. The docstrings are not helpful at all. They seem to be written for and by the developers. Not the users of the framework.

Code Example

I am trying to help a user here https://discourse.holoviz.org/t/cannot-delete-boxedit-after-adding/3985.

import skimage
import numpy as np
import holoviews as hv

from holoviews import opts
from holoviews import streams
hv.extension('bokeh')
data = skimage.data.brain()
ds = hv.Dataset(
    (np.arange(256), np.arange(256), np.arange(10), data),
    ["x", "y", "num"],
    "count",
)
polys = hv.Polygons([])
box_stream = streams.BoxEdit(source=polys)

def stats(data):
    if not data or not any(len(d) for d in data.values()):
        return hv.Text(128, 128, "N/A")
    
    x0, x1, y0, y1 = data['x0'], data['x1'], data['y0'], data['y1']
    return hv.Text(128, 128, f"x0={x0}\nx1={x1}\ny0={y0}\ny1={y1}")

dmap = hv.DynamicMap(stats, streams=[box_stream])

im = ds.to(hv.Image, ['x', 'y'], dynamic=True)
ds.to()

plot = (im * polys + dmap).opts(
    opts.Curve(width=400, framewise=True), 
    opts.Polygons(fill_alpha=0.2, line_color='red'), 
    opts.VLine(color='black')
)

hv.Dataset

The docstring is simply incomprehensible. It does not answer the most simple questions like

• What is a Holoviews Dataset?
• Why do I need it?
• How do I use it?

It does not provide a reference example or a quick link to the documentation. I cannot use this for anything. And the hv.Dataset is the starting point for most things in HoloViews !!!

hv.Polygons

Wtf. It gives me the exact same docstring !!!

hv.DynamicMap

Wtf. It gives me the exact same docstring !!!

BoxEdit

There is no description of what I can use BoxEdit for. There is no description of any of the arguments I can see !!!

Dataset.to

What is this? How do I use it?

opts

This is the most useful docstring in the example. But it would be nice if it assumed even a bit less of the user. What is an option? And why are options separate?

opts.Curve

Thanks for nothing 😃. When I see something so empty I am in doubt if I am looking at a class that is not important/ should not be used.

holoviews/ hv

This is the entry point. This is where all users will start. It has NO docstring!!!

What is this? How can it help me? What does a simple example look like? Where do I find more information?

[maximlt]

An easy win is having a link to the reference page in the docstring, this has been added by Marc to Panel and has proven to me pretty useful, Simon can confirm.

[jbednar]

Right; Dataset is a base class, but not an abstract base class. It’s useful as a concrete class that encapsulates certain functionality, and also important as the base class that implements that functionality for Elements. Thus many people need to know about it, and it’s mentioned in the docs in various places, but if someone needs to know all about it, they go to the docstring and find almost nothing, and there’s no reference manual notebook about it since it’s not an Element or Layout. So it falls in a hole between our notebooks (all covering user-relevant objects) and abstract base classes (not needing notebooks since most people don’t need to know about them).

I agree that the website is an important way to explore a graphical system like HoloViews, but I do sympathize with Marc’s quest to have information right at his fingertips in an editor, just as I’d like to have such information right at my fingertips in Jupyter. I think having an informative docstring addresses both needs. It’s true that in Jupyter we can probably handle much longer and richer docstrings, but no matter what, the current 3-sentence docstring is insufficient for such an important class.