Add how to for Makie extensions

[milankl]

following discussion in SpeedyWeather/SpeedyWeather.jl#511

@SimonDanisch @jkrumbiegel I've added a how to page on Makie extensions. Hope you find it useful. Feel free to change it as you see fit for your documentation. Also I can't see (or don't know where to look for) the link to the docs preview, if you could post it that'd be fab then I'll have a last look.

[milankl]

It looks like you don't use the [Header](@ref) syntax for links but \reflink instead?

[milankl]

@jkrumbiegel approve CI?

[milankl]

@jkrumbiegel @SimonDanisch approve and merge or request changes?

[jkrumbiegel]

Thanks for the effort! In general nicely written etc. I just don't really like the example. Of course you can overload heatmap like any other function, but these plotting functions are not your usual functions, they are rather entry points into our recipe/theming/plotting system. Which is circumvented by defining methods on them manually. I know you can technically do it, and I know that we don't yet have the canonical solution for that in Makie, but it's still not something the official docs should endorse.

I think I'd rather show how some recipe functions owned by the package can be filled in using an extension. So you define someplot and someplot! as empty functions in the package and add a recipe on top of that in the extension, like I was doing here https://github.com/jkrumbiegel/MakiePkgExtTest/blob/master/SomePackage/ext/MakieExtension.jl

[milankl]

Sorry I don't get this. You'd rather have packages that want a Makie extension not to use the Makie function like heatmap but rather come up with their own name, like visualise_my_data that then calls Makie functions like heatmap!? I'm sure there are good reasons to hook into lower level functions in the Makie logic, but I guess many package developers (like me) aren't necessarily familiar how to do that or why. So they'll presumably think about putting something on top of the top-level functions. SpeedyWeather.jl does that now, and it's exactly what we need, Tenet.jl does it, Trixi.jl does it and it seems like there's plenty more if you search for MakieExt.

As I said, I thought this would be helpful for other package developers to have some documentation of how to write a Makie extension, but if you'd like to establish another way of writing such extensions then please let me know / change this pull request so that we know how to do it the preferred way + outlining the reasons for it, because I still haven't understood yet what the advantages are to hook into the deeper Makie logic than to extend a top-level function with another method.

[jkrumbiegel]

You'd rather have packages that want a Makie extension not to use the Makie function like heatmap but rather come up with their own name, like visualise_my_data that then calls Makie functions like heatmap!

I don't know what the best solution is, the problem is that all the plotting functions defined through @recipe follow a special pipeline which takes care that heatmap(...) returns FigureAxisPlot, heatmap!(ax, ...) etc are all defined. Of course one can overload unused methods of these functions and then return whatever, for example a Figure with a heatmap plus other stuff. But these then live "outside" of the Makie system and in my opinion it gets harder to understand what's going to happen when you call them.

From my point of view it's better currently to define a simple function if you want to do a full figure with lots of stuff going on. Or a @recipe if you want to offer a reusable building block. But if people start overloading the default plotting functions and everybody comes up with their own interface what kind of options they take and how, that's going to be confusing.

I acknowledge that this is happening because we currently don't have a "complex recipe" story in Makie, as it's a complex design issue, and people are going ahead with their custom solutions because they don't have time to wait. That doesn't make the problem I described above go away.