Asciicast.jl makes it easy to include and maintain animated gifs of Julia REPL sessions in documents (like package READMEs) and in documentation.
With Asciicast, in Documenter docs, you can use @cast
blocks similar to @repl
ones. For example
```@cast
using Pkg
Pkg.status()
1 + 1
```
generates and embeds an animation of the code executing. The Documenter Usage section of the docs shows all of the options, as well as some examples.
Likewise, in documents like READMEs, you can include blocks like
```julia {cast="true"}
using Pkg
Pkg.status()
```
Then run Asciicast.cast_document
. It will parse the document using pandoc
, identify these blocks, execute the Julia code, generate a gif, save it to disk, then add an image link to the gif into the document, writing it back out. This makes it easy to update and maintain these gifs. The Markdown Usage section of the docs goes into all the details there. Also, as an aside from the animations, I think this same technique could be used to ensure README examples stay fresh, e.g. by calling something similar in the tests to execute the code.
One caveat is that we lack a precise markdown parser that maintains syntax trivia like whitespace etc, so when pandoc writes the document back out, it will effectively re-format it (in ways that should not change the rendered output, but can change the markdown file itself quite a bit).
Additionally, Asciicast.jl provides macros and other functionality to generate animations directly. They also support VSCode, to show animations in the plot pane (using the js asciinema-player, not gifs, meaning they are high resolution always).
I developed the first version of this code a few years ago to add animations to my toy package TravelingSalesmanExact, but recently expanded and updated it quite a bit, and registered it in General (it can be useful as a test dependency at least). I also tested it out on ProgressMeter.jl, and documented some limitations of my approach.
Asciicast.jl also builds on Documenter, and relies heavily on some of its internals (reusing some of it’s functionality for code parsing and execution). But perhaps it can be stable with the help of some integration tests in Documenter.
I hope it can be useful!