Render plots in @autodocs?

[tlnagy]

In Gadfly.jl it would be nice to embed plots in the autogenerated docstrings via @autodocs. For example, it would be great if I could include an example like

```@example
using RDatasets, Gadfly

df = dataset("ggplot2", "diamonds")

p = plot(df, x=:Cut, y=:Carat, color=:Cut, Geom.violin())
draw(SVG("diamonds_violin1.svg", 10cm, 8cm), p) # hide
nothing # hide

in the docstrings so that the plot shows up here: http://gadflyjl.org/latest/lib/geometries.html#Gadfly.Geom.violin. Is this possible? Currently `Documenter.jl 0.17.0` throws an error: 

!! Invalid local image: unresolved path 'diamonds_violin1.svg' in lib/geometries.md

[mortenpi]

You can't have at-blocks in docstrings at the moment, so it never gets executed.

Now, technically we could do it (although it's a bit unclear how files created in the at-blocks should be handled). But I am not sure that we want to, because docstrings should also be readable in the REPL, and so I don't think they should not rely on (Documenter-)generated content like this.

What you could do is have the docs more interleaved, having the at-block in the Markdown pages. E.g. something like:

## Violin plots

You can use [`Gadfly.Geom.violin`](@ref) to create violin plots.

```@docs
Gadfly.Geom.violin

It can be used as follows:

using RDatasets, Gadfly

df = dataset("ggplot2", "diamonds")

p = plot(df, x=:Cut, y=:Carat, color=:Cut, Geom.violin())
draw(SVG("diamonds_violin1.svg", 10cm, 8cm), p) # hide
nothing # hide

While Documenter shouldn't necessarily impose any particular style on the documentation writer, I'd say having docstrings interleaved with surrounding text is the ideal style for Documenter-generated docs. I think the [unit testing page in the Julia manual](https://docs.julialang.org/en/stable/stdlib/test/) is a good example of this style.

So I am slightly leaning towards the simpler solution of not allowing at-blocks in docstrings. But I am definitely open to counterarguments.

[timholy]

I've actually got almost exactly what you suggest here and it's still giving the same Invalid local image: unresolved path error. Any ideas?