Add scatter matrix reference

[maximlt]

This PR adds a reference page for the scatter_matrix plots. It also fixes to docstring of this function to reflect the fact that tools only support a list of tools.

[maximlt]

Could you look into this @jlstevens please?

The only thing I'm unsure about this reference notebook is that I've integrated the docstring by copy pasting it and reformatting it so that it looks better in markdown. Maybe there's a way (a directive?) to have it automatically both pulled from the code base and nicely rendered.

[jbednar]

My vote is for Param and HoloViews to support an HTML rendering of the docs for a Parameterized object, which is something I sketched at holoviz/param#425, and then that could be used here and throughout the docs.I got stuck when realizing that HoloViews' own HTML repr was being overridden by this support, but it's probably not too big a job to fix that and then improve the representation so that it works well both as docs and in Jupyter, just like xarray does. Seems like an easy win and a major step forward in usability!

[maximlt]

Oh yes that would be great except that in this particular case scatter_matrix is a bare Python function so it'd need to be turned into a parameterized object (a ParameterizedFunction object maybe) first and then use the new HTML repr.

[jbednar]

Good point, but yes, a ParameterizedFunction then, so that all documented stuff could have a similar repr.

[jlstevens]

@maximlt I'll have a look at this shortly.

[jlstevens]

Looks great! Two comments:

1. How about a minor edit/elaboration at the start:

   scatter_matrix shows all the pairwise relationships between the columns of your data. Each non-diagonal entry plots the corresponding columns against another, while the diagonal plot shows the distribution of the data within each individual column.

2. I like the parameters list but I think it is important to only focus on those specific to scatter_matrix. People need to be reminded that many options are generic and apply to all/most plot types in hvplot. I would simply list what is most important for scatter_matrix(data, chart and diagonal i.e. the unique kind options) and then remind people of the generic options and the datashading options (i.e. mention them with a link).

   I have noticed that one reason you have probably done it this way is that the behavior of the generic options sometimes applies to the diagonal or off-diagonal plots (or both). It looks to me like all the generic options apply to the off-diagonal plots unless listed in diagonal_kwds/hist_kwds/density_kwds. Is this correct? If so, I would just state that...

[maximlt]

Thanks for your review Jean-Luc! I'll make the small edit you suggest at the start. On your second point, I've actually just exposed in the docs the parameters that are in the function signature and documented in the docstring. But thinking about it more this doesn't seem like a good long-term solution, I've seen in Panel how difficult it is to properly sync the Parameters doc (in the code) with the parameters description (in the reference gallery, manually typed) of its components. So until we get a better repr for Parameterized objects or an API reference for hvplot, I would instead either not show the parameters description (remove what I've added) or just display something like print(scatter_matrix.__doc__). What do you think?

[maximlt]

I'm going ahead and merging. The last change I've made updates the intro as suggested in the review. I've removed the parameters description, even if it was somehow nice to have I believe it wasn't the right place and time to do this change. This should happen across the whole documentation once a better system to document the API parameters is found.