Understanding recipes in Plots.jl

[tbreloff]

@juliohm

In terms of documentation, I feel it was written by the authors to the co-authors. As someone coming from outside, a normal user, I can’t catch up easily, which is paradoxical since one of the goals of Plots.jl is to “just work” out of the box with no need to memorize syntax nor function prototypes. I think a lot of the attention in the docs has been put into the internal machinery and less on the available customization options, makes sense?

Creating your own recipe definitely falls into the “advanced topics” category. You need to either 1) have a good understanding of macros, dispatch, and more, or 2) “trust in the magic”. In this case, I feel like you don’t fall into either category, so you’re frustrated. Using a recipe is simple… just call plot(something).

Understanding the Plots machinery/internals should be daunting… it’s incredibly intricate and complicated. But for most purposes you shouldn’t need to understand how it works, just the rules that get you from point A to B.

The best way to fix the documentation is to ask in the gitter about specific things you don’t understand, and then write up your understanding afterwards and submit a PR (to PlotDocs.jl). I can’t possibly know what you don’t understand, and I don’t have the time to spend on rewriting documentation anyways.