I am happy to announce a very small convenience package to correctly display plots generated using the plotly.js library as interactive HTML inside documentation pages built with Documenter.jl
In many cases it’s convenient to be able to show interactive plots (as in zooming/hover events) as part of documentation pages, and packages relying on the plotly.js library are very well suited for this.
This functionality has also been the subject of many issues or discourse posts (1, 2, 3, 4)
The solutions pointed out in some of those links are in my opinion sub-optimal as they require usually to save your plot data as standalone html and then load it in the page, usually using an iframe.
The solution I tried to use in PlotlyDocumenter.jl is aimed at being as low effort to the user as possible and be very similar to just showing a plot outside of Documenter.
The package exports a single function to_documenter that takes a plot object and creates an HTML output that can directly be rendered inside Documenter pages when included as last statement (i.e. the output) inside @example blocks of Documenter.
While I initally tried having this work also inside @eval blocks to hide the code input, the discussion in this recent discourse post shows that it is not currently possible, I have a PR to documenter attempting to also bring this functionality to @eval blocks but for the time being @example blocks are powerful enough.
The package is very lightweight and exploit the new package extensions functionality to only created methods for different plot objects when the relevant package is loaded. It also uses cjdoris/PackageExtensionCompat.jl: Makes Julia’s package extensions backwards compatible (github.com) to provide similar functionality for previous julia versions (1.6 julia should also be supported).
At the moment the plot objects from the following packages are supported:
- PlotlyBase
- PlotlyJS
- PlotlyLight
I am mostly familiar with the PlotlyBase ecosystem but it was super easy to also include PlotlyLight so I did add that as well.
I tried making the plotly backend from Plots.jl work but the internal structure of Plots is quite complex and I didn’t find a fast way to extract the PlotlyBase.Plot object from the plot object in Plots.jl. Help understanding how to do that is welcome and I would add support to Plots.jl if it’s easy enough.
Have a look at the package documentation to see the parameters supported by to_documenter and to show some example of how the plots will rendere in the documentation pages.