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.

[iago-lito]

@AntonReinhard You can make it fail like so:

try  #hide
throwing_call()
throw("Unexpected success.") #hide
catch err; showerror(stderr, err); end  #hide

[AntonReinhard]

@AntonReinhard You can make it fail like so:

try  #hide
throwing_call()
throw("Unexpected success.") #hide
catch err; showerror(stderr, err); end  #hide

This would just print "Unexpected success." when throwing_call() does not throw. I would want it to fail while building the docs.

[iago-lito]

@AntonReinhard println("Unexpected success") would just print it, but throw("Unexpected success") will make whatever process fail, unless the string is caught by Documenter, which I doubt ;)

[AntonReinhard]

@AntonReinhard println("Unexpected success") would just print it, but throw("Unexpected success") will make whatever process fail, unless the string is caught by Documenter, which I doubt ;)

I mean you are explicitly catching and printing it, so of course it gets caught. I just tried it.

[iago-lito]

Wops! Sorry I get what you mean. The actual workaround would be much more verbose indeed :(

struct UnexpectedSuccess <: Exception end #hide
try  #hide
throwing_call()
throw(UnexpectedSuccess()) #hide
catch e; e isa UnexpectedSuccess ? rethrow(e) : showerror(stderr, e); end  #hide

So, yeah, having a nice option for this + auto implementation of Base.showerror(::IO, ::UnexpectedSuccess) would be nice.