How do we want our HTML repr to behave?

[jbednar]

Different libraries use HTML reprs differently. E.g., here are the reprs for a Pandas DataFrame and an Xarray DataArray:

import pandas as pd
df = pd.DataFrame(dict(x=[1,2,3],y=[2, -1, 5]))
df

import xarray as xr, numpy as np, pandas as pd

temperature = 15 + 8 * np.random.randn(2, 2, 3)
lon = [[-99.83, -99.32], [-99.79, -99.23]]
lat = [[42.25, 42.21], [42.63, 42.59]]
time = pd.date_range("2014-09-06", periods=3)
reference_time = pd.Timestamp("2014-09-05")
da = xr.DataArray(
    data=temperature,
    dims=["x", "y", "time"],
    coords=dict(
        lon=(["x", "y"], lon),
        lat=(["x", "y"], lat),
        time=time,
        reference_time=reference_time),
    attrs=dict(description="Ambient temperature.", units="degC"))
da

The DataFrame doesn't declare that it is a DataFrame or a Pandas object, presumably because a DataFrame has a very natural and complete representation as a table that is useful and understandable in many contexts even for non-programmers, so having a minimal representation like that is directly useful. The DataArray, on the other hand, is more difficult to represent on a 2D page because it is potentially n-dimensional, which is perhaps the reason that Xarray shows it as a rich object that has multiple attributes that can be expanded or contracted as needed.

A Parameterized has a natural representation as a table of key:value pairs, but such a representation is highly incomplete, because it fails to convey the range of values that are possible settings. The current Parameterized repr is more like the xarray repr in that it conveys additional information about ranges, types, etc. in an expandable table:

Notice that the Xarray repr shows the type of the whole container object (a DataArray), while Param does not show that it's a param.Parameterized. I do find the object type useful, so I propose we add it. If we follow the Xarray formatting I think we'd get option (1):

Because we have only one such section, we could consider one-line representations (2):

and (3) (depending on what the HTML details/summary tags support):

If we do switch to an unexpanded one-line repr by default, then we could reconsider whether to show an HTML repr for the bare object. E.g. right now we show what seems like a less-useful text repr for just p or P:

Both DataFrame and DataArray show the HTML repr for the equivalent of p but not for P. Using an HTML repr for P has the unfortunate sideffect of showing a rich repr for type(p), so maybe we should continue with the current text repr for P. Still, if we go with the one-line reprs that include the type information maybe we can consider an HTML repr for P as well as for p?

Also note that for docs we will need a table representation that includes the Parameter docstring, currently visible only on hover. Maybe we can adapt the HTML repr to include the docstrings and then be used for the output of help()?