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:
https://github.com/JuliaDocs/IOCapture.jl/pull/9/commits/6cb4cdff34cd8f5d416bc4d0e36fe118e3f4d0bc.
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.
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[])
Giorgio Calderone
gcalderone
Michal Sojka
Jarvist Moore Frost
Páll Haraldsson
Adam Lyon