Including an image in a docstring output?

[tlnagy]

It would be awesome to include image output in the docstrings using Base.show. Currently, this works great with @example blocks that are defined in the markdown files, but there isn't any image output if the same code is included in an @example block or a doctest in the docstring.

This would be a great addition to have!

[mortenpi]

Well, you can generate a file and just use the Markdown ![]() syntax to include it. But in general, I don't think this is good practice -- docstrings should be readable in the REPL. To support this nicely, you'd need some sort of DocStringExtensions-based/like solution.

[tlnagy]

We have such nice live tests in docstrings via doctests, but there isn't anything (AFAIK) for visual output. I guess I could include it in the documentation separately and have the array output in the doctests...

[heliosdrm]

If what you want is to include examples in docstrings that produce an image, and then show them in the documentation pages (without repeating yourself), this workaround does the trick:

(All paths in this explanation are relative to the root of the package.)

Put the code of the example in a .jl file like examples/exampleplot.jl

In the docstring where you want to include that example, write (assuming that it is in a file within src):

 ```julia
 $(read(joinpath(dirname(@__FILE__), "../examples/exampleplot.jl"), String))
 ```

And in the md file of the documentation:

```@docs
function_to_document
```
```@example
Base.include(Main, "../examples/exampleplot.jl") # hide
```

[SimonDanisch]

I'd like this too!

But in general, I don't think this is good practice

I don't agree. I'm putting nice code examples into the docstring for people to try out and get a feel how to use something. Of course they wont get an output in a text repl for this, but why shouldn't they in Documenter? E.g.:

"""
    StylableSlider(
        range::AbstractVector;
        ....
    )

...

# Example

``@example
using JSServe
App() do
    JSServe.StylableSlider()
end
``
"""

I think this is a totally fine docstring, and having this in the docs with rich output, would be really nice for the docs :) @heliosdrm solution works but is a bit cumbersome.

I thought a variation of this may work:

``@example 1
open(io-> show(io, "text/markdown", @doc StyledSlider), "styledslider.md", "w")
``
![](styledslider.md)

But it doesn't really get "copy & pasted" into the document... Is there any compromise like the above, that I'm overlooking? Any way to render a markdown object exactly like the documenter markdown file?