Writing a user guide (or how to include benchmarks) about documenter.jl

[MichaelHatherly]

So, I suggest to have the functionality of {example} with the possibility of inserting the "julia> " prompt after parsing.

Yes, sounds like a good addition.

The implicit meaning of the {...} syntax is that it denotes generated content, whereas doctest blocks only compare results without creating anything new. Following that approach would indeed lead to implementing this with a {example-repl}, or perhaps just {repl}, rather than as a .language name.

(Switching over to #5 is possible, but at this point there's already quite a lot of code out there using the current syntax, so I'm not sure whether changing would be all that beneficial.)

Regarding some more specific concerns about a possible {repl} syntax:

• Would julia> be added infront of every toplevel expression, or would it be possible to group several like you can do with alt-return in the real REPL?
• Semi-colons would presumably hide output as usual?

[lbenet]

I like the name {repl} for such a mode.

Ideally, and considering the case of a user guide, the code

    {repl}
    a = 2
    b = 3
    c = 4; 
    a + b

should produce

julia> a = 2
2

julia> b = 3
3

julia> c = 4;

julia> a+b-c
1

That is, unless we use explicitly the semi-colon, the result appears right after the executed line. (This saves typing lots of {example} or {repl} blocks, if this is the intended output.) For grouping several lines, mimicking alt-return, probably {repl-block} would be the way to go, and the output should correspond only to the last statement, just as the REPL behaves.

[lbenet]

Incidentally, part of this issue was actually motivated because, when I used {example} and @time whatever(); (note the semicolon at the end), the output from whatever(); was not suppressed.

[MichaelHatherly]

the output from whatever(); was not suppressed.

You can get the same effect, if I'm understanding correctly, with a nothing # hide line as in

    {example}
    f(x) = (sleep(2x); 3x)
    @time f(1)
    nothing # hide

Not the most elegant, but it should work.

probably {repl-block} would be the way to go

Having an additional {...} just for that would probably not be worth it. Grouping things like that isn't too important for a first implementation though.

[lbenet]

Thanks for the provided code; it indeed works nicely (except for the missing julia>...

You are right, there is no need for another type of grouping.

[MichaelHatherly]

{repl} blocks have been added in 7168524.

[lbenet]

Thanks!