This change fixes incompatibility of Gnuplot.jl with Documenter.jl
versions 0.27.0 and above. Without this change, Gnuplot.jl has at
least these problems:
1. When building Gnuplot.jl documentation, the process blocks and
never finishes.
2. When using Gnuplot.jl in docstrings in other code, running
`doctest` blocks and never finishes.
The reason is that Documenter uses a new version of IOCapture.jl,
which contains this commit:
6cb4cdff34.
Documenter evaluates code snippets from the documentation with
`stdout` redirected to a pipe to show the command's output. The
mentioned commit changes the behavior so that now capturing waits
until the pipe is closed. The problem with Gnuplot.jl is that when the
gnuplot process is started as a part of the execution of documentation
code snippet, its `stdout` is bound to Documenter's pipe. The pipe is
not closed until the gnuplot process exits, which does not happen
unless the code snippet calls `Gnuplot.quit` explicitly. Therefore
Documenter blocks indefinitely.
This can be demonstrated by storing the following code in `test.jl`
module GnuplotDocTest
"""
```jldoctest; setup = :(using Gnuplot)
julia> @gp rand(100)
```
"""
test() = nothing
end
using Documenter
doctest(pwd(), [GnuplotDocTest])
and running `julia test.jl`.
To fix this problem, we run the gnuplot process with stdout redirected
to a pipe and create an asynchronous task, which reads the gnuplot's
stdout and writes it to Julia's current stdout.
Correctness of this approach can be verified by running:
using Gnuplot
Gnuplot.options.term = "dumb"
@gp "plot sin(x)"
Dumb terminal prints to stdout and the above command shows the graph
on Julia's stdout too. In the next commit, we add the above code as a
doctest.
When the plot pane is disabled, VS Code neither shows the plot nor
prints any warning/error. The plot is not shown because Gnuplot.jl
thinks the VS Code can display it. We fix that by adding a check for
whether the pane is enabled.
This is not an ideal solution because the check is executed only when
loading Gnuplot.jl. If the panel is disabled later in the REPL
session, no plots will be shown. If this turns out to be a problem, we
will need to extend `showable` and perform the check there.
The problem of not showing a warning/error when the plot pane is
disabled must be addressed in julia-vscode. It seems that the Plots
package doesn't produce any warning/error in this case too.
Related to #45.
Using the @gnuplotrc macro for collecting user's preferred setup works
well, but it is a bit annoying when Julia needs to be restarted
often (e.g. due to crashes). Using Requires.jl allows the user to
forget about calling @gnuplotrc; the initialization happens
automatically, whenever the Gnuplot package is loaded.
With this change, when Gnuplot.jl is used within VSCode, the plot
shows in VSCode plot pane instead of in a separate Gnuplot window.
Note that when compared to IJulia and Juno, we do not test for active
VS Code connection. I don't think it is necessary, but if it turns out
to be needed later, it can be done with
isopen(VSCodeServer.conn_endpoint[])
