search

holoviz / holoviews

With Holoviews, your data visualizes itself.
https://holoviews.org
BSD 3-Clause "New" or "Revised" License
2.7k stars 403 forks source link

Documentation: hv.Dimension: positional argument not documented #2947

Open wmayner opened 6 years ago

wmayner commented 6 years ago

I'm finding myself a bit perplexed by the documentation system used throughout Holoviews.

For example, when I try to learn how to use hv.Dimension, there doesn't seem to be any information on the positional argument (which I now know should be the dimension's name). This issue is similar to #2925.

  1. help(hv.Dimension) only documents keyword arguments (Params)
  2. hv.help(hv.Dimension) only documents keyword arguments
  3. The API docs only document keyword arguments
  4. The positional argument is called spec, which doesn't indicate that it should be the name of the dimension (I looked at the source and I see why this is the case, but it compounds the above issues)

The only place where name is mentioned as an argument is in the user guide. This is misleading as currently written, because it suggests that the spec positional argument is a keyword argument called name. It also suggests that name is a Param documented by hv.help(hv.Dimension), which isn't the case.

I think non-Param arguments could be documented more clearly throughout.

Gordon90s commented 6 years ago

I second that. Took me a few hours to figure it out.

I think it would be great to have examples within the documentation.

jlstevens commented 6 years ago

I agree that we should improve the docs here. We should clarify in the user guide that there is one positional argument (called spec as you say) of which the most common form of spec is simply the dimension name. Then we can document the less used tuple formats that are the other supported spec arguments.