Show the error message on purpose?

[dkarrasch]

I wanted to show some error message in the docs on purpose, but I realized that (by default) Documenter.jl is not going to show it, but give a warning in the docs build step. Is there an easy hack how to display the error warning? Ideally, I wouldn't want to distract the reader with display details, so I'd like to show only the call that would trigger the error.

[fredrikekre]

Do you have an example? Is this in a doctest or @example block?

[dkarrasch]

It's an @example block, generated with Literate.jl. An example could be

```@example custom
rand(2,2)'ones(3)

[mortenpi]

I think the short answer here is that for an at-example block, no. But it should work as you expect if you convert it to a doctest.

We expect the the at-blocks to run successfully. Or, rather, if they fail, it's probably an error the user wants to know about. Potentially though we could have an option for at-example blocks that explicitly allows the blocks to error (and prints the error as the output, I guess?).

As a quick fix, you could rewrite your code with try ... catch and handle the exception yourself? I.e.

```@example
try
    rand(2,2)'ones(3)
catch e
    @error e
end
```

[odow]

I had this issue as well. Here was the work-around I came up with:

```@example
try  #hide
rand(2,2)'ones(3)
catch err; showerror(stderr, err); end  #hide
```

Just calling @error e isn't sufficient because the string representation of the error is often different to showerror.

Presumably, the fix for this issue is to add a

```@example; allow_error=true
rand(2,2)'ones(3)
```

which rewrites the block to the above.

[mortenpi]

Yep, a keyword argument for the at-blocks. I think #1447 is adjacent to this.

[iago-lito]

The solution of @odow works great, but is broken by JuliaFormatter pass. Unfortunately, there seems to be no way to #! format: off # hide at the same time ^ ^" A keyword argument would solve this as well.

[AntonReinhard]

It would also be great if this keyword is added, that it then requires the example to throw.

try  #hide
throwing_call()
catch err; showerror(stderr, err); end  #hide

Works well, but it doesn't fail when the statement unexpectedly doesn't throw.