feat: write at-example outputs over threshold to a file

[mortenpi]

Building on top of @jvaverka's contribution. Close #2143.

• Currently only implemented for PNG. Expand for other binary images.
• Expand for SVG -- it's a bit more complicated, so needs testing.
• Tests-tests-tests.

[mortenpi]

This should essentially be good to go, except for the complication described in #2143 (comment).

[mortenpi]

@odow Would you by any chance have time to test this branch with JuMP, see if it helps with the page sizes? I actually suspect it might not be as useful as I had hoped due to #2143 (comment).

[odow]

Let me have a go

[mortenpi]

One possibility to work around the text/html issue:

Check the size of text/html. If it is over the size limit, check if shows for any of the file-based image ones are available. If yes, use one of those (with a warning saying that text/html MIME was ignored due to size). If not, write text/html, but issue a warning that it's above the size threshold.

[odow]

Aren't the images just svg blocks? Couldn't we write them to files?
https://github.com/jump-dev/JuMP.jl/blob/104d2a4e8fbfec887f1702170a39b90b25fb9f11/v1.14.1/tutorials/getting_started/getting_started_with_data_and_plotting/index.html#L14C12-L14C12

[mortenpi]

Aren't the images just svg blocks?

Yes, but they are generated using the text/html show method, so we can't really reliably determine whether they are pure SVG or not.

[mortenpi]

One user-level hack here is to define

Base.showable(::MIME"text/html", ::Plots.Plot) = false

in your make.jl, which will make Documenter ignore the text/html representation.

[mortenpi]

Documenter should now print just a single warning that looks something like this:

┌ Warning: For 3 @example blocks, the 'text/html' representation of the resulting
│ object is above the the threshold (example_size_threshold: 8192 bytes).
│ - 1 blocks had no image MIME show() method representation as an alternative.
│   Sticking to the 'text/html' representation (largest block is 121034 bytes).
│   On pages: index.md
│ - 2 blocks had 'image/svg+xml' fallback image representation available, using that.
│   On pages: index.md, plots.md
└ @ Documenter.HTMLWriter ~/juliadocs/Documenter/src/html/HTMLWriter.jl:779