`@gif` block

[ericphanson]

I think it would be awesome if there was an @gif block that acted like an @repl but instead of printing the commands linearly, it generated an asciinema gif and inserted it. I made a prototype of sorts in https://github.com/ericphanson/TravelingSalesmanExact.jl/pull/16. See it in action here: https://ericphanson.github.io/TravelingSalesmanExact.jl/v0.3.7/#Example, or in a screenshot:

There are a lot of things to be unhappy with in my hacky version:

1. asciinema is a python dependency, so this might be kind of annoying if it was installed by default
   • perhaps it can be opt-in somehow?
2. I spin up a new Julia process to run the code for the gif
   • so with this method it would be very hard to support named blocks (@repl 1 etc).
   • and every time making a gif hits first-call compile time latency (which usually I amortize by calling include("docs/make.jl") repeatedly when developing docs). I therefore setup caching system to prevent re-making the same gif over and over, but I'm not sure it's robust enough for Documenter.jl's large userbase
3. I didn't mess with any Documenter internals to actually make a new block; I just use @example and run a string macro.
4. I ran into #1433 and worked around it in a very fragile way
5. right now, I create the gif at macro-expansion time; probably it should be at runtime? They are not very different times with example blocks though and doing stuff at top-level scope
6. asciinema is licensed GPL v3, so maybe there would be license issues?

However, I still think the result is super cool! Any ideas on how to get some (better?) version of this into Documenter.jl?

[ericphanson]

I realized asciinema is based on a simple JSON-based specification: https://github.com/asciinema/asciinema/blob/asciicast-v2/doc/asciicast-v2.md. So I quickly whipped up a Julia implementation, which lets us avoid issues 1 and 6. The inline HTML player is apache licensed so no issues there. Then I went ahead and looked at the Documenter internals and made an @gif block based on the code for @repl. This resolved issues 2, 3, and 5. The result is https://github.com/ericphanson/Asciicast.jl.

So the only remaining issue AFAIK is getting the JS loaded in the correct order (issue 4), and not relying too much on Documenter.jl internals. And testing it.

It works for my example at least: https://github.com/ericphanson/TravelingSalesmanExact.jl/pull/17 (rendered here: https://ericphanson.github.io/TravelingSalesmanExact.jl/dev/)

[fredrikekre]

Couldn't Asciicast.jl just define a type that is showable for text/html?

[ericphanson]

Yes but then you can’t use setup blocks or share state between examples and gifs etc (https://ericphanson.github.io/Asciicast.jl/dev/#Example-with-a-named-block). Well I guess technically if I’m messing with internals then I can still, but I don’t really get what the point is in that case.

But that might still be nice if someone wanted to use it in Pluto or something.

[mortenpi]

This is really neat, but I am not sure we want this in core Documenter. I would suggest implementing this as a separate package which adds a new ExpanderPipeline step.

DocumenterCitations can probably offer some inspiration if need be, and #1648 is probably also be relevant for this.

[ericphanson]

Ok, sounds good! Is the ExpanderPipeline considered stable by the way? Also I already did implement it in Asciicast.jl 😄

[mortenpi]

It's de facto stable... as in no-one has broken it ever. But we may in the future. Documenter's internals are not really documented and need refactoring if we truly want to support plugins long-term.

However, that's unlikely to happen any time too soon, and once it does, we'll try to do it in a way to keep the plugins working, including making PRs against the plugins to update the parts where it interacts with Documenter.

All that said, what could be nice is a PkgEval-like CI job here that would test whether the latest version of each plugin still passes all its tests when running against Documenter#master.

[RoyiAvital]

It would be great to have an option for APNG as well.

[ericphanson]

As a followup, Asciicast.jl is updated for Documenter v1.0 and is registered (xref https://discourse.julialang.org/t/ann-asciicast-jl/107529).

All that said, what could be nice is a PkgEval-like CI job here that would test whether the latest version of each plugin still passes all its tests when running against Documenter#master.

I will PR a workflow for this!