Add user guides for working with core class types

[philippjfr]

HoloViews has a number of core class types which define most of the core API of HoloViews but also cover many of the core concepts and terminology of holoviews. Other libraries like xarray and pandas have nice intros for the main classes, I'd suggest we have similar user guides to cover our core objects:

• Dimension and Dimensioned
  • Methods: redim, relabel, range, dimension_values, select, map, traverse
• NdMapping types: HoloMap, NdOverlay, GridSpace, NdLayout
• Tree types: Overlay and Layout
• Dataset and Interfaces
  • Methods: sample, select, reduce, aggregate, groupby etc. ...

These materials will be a lot more dry than one of our existing tutorials but I think this would be a good way of capturing the core API in detail.

[PeterDSteinberg]

I'll add a couple questions from my own experience that would be nice to address in this work:

• If I use Layout [tabs=True tight=True] in a cell, how do I adjust what the text of those tab links says (default is "Image 1", "Image 2", etc at top of each tabbed plot)
• A walk through on making a 2 plot widget with 2 sliders controlling the plots. I know we have this sort of thing already, but I think the sliders part is not explained quite enough, like can I have tuple keys of the dictionary in order to make as many sliders as the length of tuples, and what about continuous vs categorical controls of plots.
• A single place in docs, like a glossary, where we define and demo some of the re-used argument names would be helpful, e.g. kdims, cdims, vdims, etc. This is helpful for users less into object oriented code or new Python users who may not realize exactly which class(es) they are using or where to look for help.
• An explanation of why choose geoviews, holoviews, and/or datashader and explaining their interactions, limitations, and further development status.

[jbednar]

An explanation of why choose geoviews, holoviews, and/or datashader and explaining their interactions, limitations, and further development status.

This should definitely be a part of the shared integrative docs site that we have agreed to make, and then each project can link back to it.

[PeterDSteinberg]

Another item that would be nice:

• More docs on adding titles to figures, titles to each subplot in a layout and other annotation. From the docs now I have found out how to control formatting of text more easily than I figured out how to set what the text of a title is.

[PeterDSteinberg]

One more example. In the following code:

x = hv.Dataset(x, kdims=['x', 'y'], vdims=['metstat_dir_wh_m_2'])
hv.Points(x, kdims=['x', 'y'], vdims=['metstat_dir_wh_m_2']))

it is not immediately apparent why I would give kdims and vdims to Dataset and/or Points.

[philippjfr]

@PeterDSteinberg Thanks for these suggestions I agree with all of them.

If I use Layout [tabs=True tight=True] in a cell, how do I adjust what the text of those tab links says (default is "Image 1", "Image 2", etc at top of each tabbed plot)

Currently this is controlled via the group and label but it should really be the regular title of the subplot which can be controlled with the title_format.

A walk through on making a 2 plot widget with 2 sliders controlling the plots. I know we have this sort of thing already, but I think the sliders part is not explained quite enough, like can I have tuple keys of the dictionary in order to make as many sliders as the length of tuples, and what about continuous vs categorical controls of plots.

Agreed, a walkthrough of how the default widgets work would make a good user guide entry.

A single place in docs, like a glossary, where we define and demo some of the re-used argument names would be helpful, e.g. kdims, cdims, vdims, etc. This is helpful for users less into object oriented code or new Python users who may not realize exactly which class(es) they are using or where to look for help.

A glossary seems like a great idea.

An explanation of why choose geoviews, holoviews, and/or datashader and explaining their interactions, limitations, and further development status.

A Roadmap or Vision section on the website also seems like a good idea. It can link to the integrative documentation as necessary.

More docs on adding titles to figures, titles to each subplot in a layout and other annotation. From the docs now I have found out how to control formatting of text more easily than I figured out how to set what the text of a title is.

A general section with a more plotting centric focus showing how to customize axes, titles, etc. is something I've long felt was missing.

[jlstevens]

I also think a glossary is a great idea. I've started working on defining some terms in the holoviews-contrib wiki. It is obviously work-in-progress but once it is more complete and polished, we'll move it to its own page on the website.