using `figure` placeholders to get hard copy placeholders, can break the web experience for altair

[stevejpurves]

Currently the figure directive has a :placeholder: option that I have been using in the following ways:

1. Given an figure based on an ipywidgets notebook output, I can provide an image to use in a myst website on immediate load, where no output is otherwise available, and this will also be used in hard copy pdf export
2. Given an altair based figure, I can use the placeholder to provide an image that is used when generating a pdf from the document

However, in case 2 the interactive Altair outputs are no longer rendered by myst-theme, and the placeholder is used instead, meaning I need to connect to a kernel (if possible/enabled) and execute the figure/notebook before I can interact with the plot. this defeats the object of the altair plot.

Proposal

We add a :hard-copy: option to the figure such that we can satisfy case 2. without having to accept the :placeholder: behaviour, which is desirable in case 1. :hard-copy: should be preferred over :placeholder: in pdf/doc builds if both are set, and :placeholder: would be used in absence of explicit :hard-copy:

Additional notes

I have considered that the theme could use logic to somehow prioritise altair/vega's mimetype over the static image or placeholder. While that is possible, it leads in to very specific prioritisation and other/future jupyter outputs that warrant the same changes would require theme updates to support. A new option communicates the author's intent better too.

[agoose77]

@stevejpurves I wonder if this is something that the code-cells should be doing instead.

For my thesis, I created a displayed_as_mimebundle context manager that takes e.g.

display(image)
display(html)

and produces

display({
  "text/html": ...,
  "image/png": ...
}, raw=True)

I think this kind of approach makes more sense; it leans in to using MIME preference to determine which output is rendered, and avoids us having to encode this kind of logic (and build the figure outputs in different cells)