Documenter.jl: 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.

md ```@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:
`Julia @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 
````Julia
```@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.