Write display() calls in markdown output

[gbruer15]

@fredrikekre I made some changes to get the display() calls rendered for the markdown output, but I don't understand the multiple MIMEs for the same display() call. And I don't understand the use for the split_mime() call.

So this is an initial fix, but it seems to duplicate output to both plain text and HTML. Can you advise on the correct behavior?

Fixes #255

[fredrikekre]

Jupyter notebooks are a bit different because they can store multiple representations. In the case of Markdown I think we should mirror Documenter and only display a single one perhaps.

[fredrikekre]

I don't remember what Documenter does with explicit display calls, do you know?

[gbruer15]

I don't know, but I'll look into it.

[gbruer15]

It looks like Documenter.jl does not handle display() calls. It does mime dict processing of the single output of the cell:

• Generate the mime dict here: https://github.com/JuliaDocs/Documenter.jl/blob/a0257f939c2be20c7a68ecc02c4ada8210f29495/src/utilities/utilities.jl#L541-L558
• Process the mime dict here: https://github.com/JuliaDocs/Documenter.jl/blob/a0257f939c2be20c7a68ecc02c4ada8210f29495/src/expander_pipeline.jl#L781-L785
• Choose which output type to show here: https://github.com/JuliaDocs/Documenter.jl/blob/a0257f939c2be20c7a68ecc02c4ada8210f29495/src/html/HTMLWriter.jl#L2348-L2471

Also, QuartoNotebookRunner.jl does similar processing but just hands the outputs back to quarto:

• Generate the mime dict here: https://github.com/PumasAI/QuartoNotebookRunner.jl/blob/899d41ab0f7183b4d2c09d7bce78ee74842e4ae4/src/QuartoNotebookWorker/src/render.jl#L323-L418
• Save the mime dicts from each display() here: https://github.com/PumasAI/QuartoNotebookRunner.jl/blob/899d41ab0f7183b4d2c09d7bce78ee74842e4ae4/src/QuartoNotebookWorker/src/InlineDisplay.jl#L16-L30
• Process the mime dict here: https://github.com/PumasAI/QuartoNotebookRunner.jl/blob/899d41ab0f7183b4d2c09d7bce78ee74842e4ae4/src/server.jl#L1012-L1052
• Add to list of cells here: https://github.com/PumasAI/QuartoNotebookRunner.jl/blob/899d41ab0f7183b4d2c09d7bce78ee74842e4ae4/src/server.jl#L671-L805
• And then the list of cells is written to JSON, probably to be processed by quarto.

I think Literate.jl markdown format just needs something like the domify() of Documenter.jl.

[gbruer15]

This is working now with images, markdown, and plain text outputs. I don't know the right way to handle displaying the latex. Right now, I simply wrapped it in "latex" and "".

[fredrikekre]

I will find time to review, but can you comment on what happens if there is an explicit display call and a value that can be showed in the same cell?

[gbruer15]

The results of the display calls are shown in order, and then the return value is displayed.

Example

Consider this example script:

struct DF{N} x end
DF(x) = DF{x}(x)
Base.show(io::IO, ::MIME"text/plain", df::DF{1}) = print(io, "DF($(df.x)) as text/plain")
Base.show(io::IO, ::MIME"text/html", df::DF{2}) = print(io, "DF($(df.x)) as text/html")
Base.show(io::IO, ::MIME"image/png", df::DF{3}) = print(io, "DF($(df.x)) as image/png")
Base.show(io::IO, ::MIME"text/markdown", df::DF{4}) = print(io, "DF($(df.x)) as text/markdown")
Base.show(io::IO, ::MIME"text/latex", df::DF{5}) = print(io, "DF($(df.x)) as text/latex")
Base.show(io::IO, ::MIME"image/svg+xml", df::DF{6}) = print(io, "DF($(df.x)) as image/svg+xml")
Base.show(io::IO, ::MIME"image/png", df::DF{7}) = print(io, "DF($(df.x)) as image/png")
#-
foreach(display, DF(i) for i in 1:6)
DF(7)

Notebook (as generated)

The generated notebook can't display the images because they aren't valid, and the markdown and svg output aren't right.

Notebook (after running kernel)

If I run the kernel, the markdown and is more correct, although I'm not sure it they should look like. And the svg doesn't show up, probably due to being invalid.

Markdown (execute=false)

The markdown example with execute=false doesn't show the displays.

Markdown (execute=true)

The markdown example with execute=true doesn't show the images, probably since they're invalid. But I have tested with actual images and they showed up correctly.