Show a tabular view of InventoryItems in rich-MIME environments

[kellertuer]

When currently “browsing” the existing names one gets something like

julia> links["ManifoldsBase"]("copyto!")
4-element Vector{DocInventories.InventoryItem}:
 InventoryItem(":jl:method:`Base.copyto!-Tuple{AbstractManifold, Any, Any, Any}`" => "functions/#Base.copyto%21-Tuple%7BAbstractManifold%2C%20Any%2C%20Any%2C%20Any%7D")
 InventoryItem(":jl:method:`Base.copyto!-Tuple{AbstractManifold, Any, Any}`" => "functions/#Base.copyto%21-Tuple%7BAbstractManifold%2C%20Any%2C%20Any%7D")
 InventoryItem(":jl:method:`Base.copyto!-Tuple{AbstractPowerManifold{𝔽, <:AbstractManifold{𝔽}, NestedPowerRepresentation} where 𝔽, Any, Any, Any}`" => "metamanifolds/#Base.copyto%21-Tuple%7BAbstractPowerManifold%7B%F0%9D%94%BD%2C%20%3C%3AAbstractManifold%7B%F0%9D%94%BD%7D%2C%20NestedPowerRepresentation%7D%20where%20%F0%9D%94%BD%2C%20Any%2C%20Any%2C%20Any%7D")
 InventoryItem(":jl:method:`Base.copyto!-Tuple{AbstractPowerManifold{𝔽, <:AbstractManifold{𝔽}, NestedPowerRepresentation} where 𝔽, Any, Any}`" => "metamanifolds/#Base.copyto%21-Tuple%7BAbstractPowerManifold%7B%F0%9D%94%BD%2C%20%3C%3AAbstractManifold%7B%F0%9D%94%BD%7D%2C%20NestedPowerRepresentation%7D%20where%20%F0%9D%94%BD%2C%20Any%2C%20Any%7D")

Would it maybe make sense to

• have a show method for the Item to be displayed a bit nicer?
• maybe even having a show method for the vector to display as a table or at least separated by tabs (or also a header)?

I was thinking maybe of something like

Vector{InventoryItem} with the following elements

| Role     |    name    |   URL |
|  :jl:method:` | Base.copyto!-Tuple{AbstractManifold, Any, Any, Any}` | `functions/#Base.copyto%21-Tuple%7BAbstractManifold%2C%20Any%2C%20Any%2C%20Any%7D")` |
...

where my own main problem would probably be the alignment.

[kellertuer]

Ah this might maybe be more something for DocInventories.jl? Just tried to find this in the Repo here and noticed, that the type is defined over there and even has a nice show method itself. Still I do not yet directly see how to propose a new show/repl view yet.

[goerz]

have a show method for the Item to be displayed a bit nicer

It already has, and what you're seeing is a heavily compressed form, down from e.g.,

julia> print(repr(inv("copyto!")[1]; context=(:full=>true)))
InventoryItem(name="Base.copyto!-Tuple{AbstractManifold, Any, Any, Any}", domain="jl", role="method", priority=1, uri="functions/#Base.copyto%21-Tuple%7BAbstractManifold%2C%20Any%2C%20Any%2C%20Any%7D", dispname="Base.copyto!-Tuple{AbstractManifold, Any, Any, Any}")

Unfortunately, both the names and URIs for methods (as opposed to functions/types) tend to be very long, which makes even the compressed show cumbersome, but that's not something I have control over.

In general, the InventoryItem representation is somewhat constrained by convention. The 2-arg show (which produces single-line representations, used for string interpolation and also for the display of items in a vector) is recommended to "be parseable Julia code when possible", which is an idea that I very much agree with. But that means you can't do much more than choosing the shortest possible valid constructor that would result in that InventoryItem by showing the Inventory(pair; kwargs...) constructor and stripping out all keyword arguments that have the default values, which is what I'm doing.

maybe even having a show method for the vector to display

I remember discussions about this on Slack or Discourse, and it's something that's frowned upon (or at least a gray area): I don't own Array, and it's debatable whether I own Array{InventoryItem}, or whether defining a custom method for show would be type piracy. I somewhat agree with the consensus that it's best to have uniform rendering of arrays and to not define custom methods for Vector{InventoryItem}.

So that puts this pretty much off limits as far as the REPL is concerned. It would be an option to have a show_as_table function (which I would own, so no type piracy problem), and that could print the text in an arbitrary format. But

| Role     |    name    |   URL |
|  :jl:method:` | Base.copyto!-Tuple{AbstractManifold, Any, Any, Any}` | `functions/#Base.copyto%21-Tuple%7BAbstractManifold%2C%20Any%2C%20Any%2C%20Any%7D")` |

(with alignment) would result in a very wide display, and be pretty broken whenever the terminal width is less than the table width (which should be quite often). So I just don't think tables view are suitable for dispay in the REPL. Unless you control the max width of the columns, but that would lose important information.

What would make sense is to implement Base.show(io::IO, ::MIME"text/html", inventory::Inventory) so that it shows a nicely rendered table in an HTML context like a Jupyter/Juno notebook. That's definitely something I've been considering and will probably do at some point (but it's not a super high priority, so it might be a while to get around to it).

It won't do anything for a vector of InventoryItems, again because I don't own the show for Vector, but also there a show_as_table function would be fine.

So I think this is a "wontfix" in the context of the REPL, but I'll leave this open for display in other MIME-type environments.

[kellertuer]

Instead of the Array one could of course also do a fancier show for a whole inventory only,
but you are right, since a show already exists, maybe a html-show or a markdown show would probably be the way to go here.