add Preferences note (#331)

Author: t-bltg

docs/ci_build.sh

@@ -46,10 +46,10 @@ if true; then
   export DOCUMENTER_DEBUG=true  # Democards.jl
 fi
 
+export LD_PRELOAD=$(g++ --print-file-name=libstdc++.so)
 export GKSwstype=nul  # Plots.jl/issues/3664
 export COLORTERM=truecolor  # UnicodePlots.jl
 export PLOTDOCS_ANSICOLOR=true
-export LD_PRELOAD=$(g++ --print-file-name=libstdc++.so)
 
 julia='xvfb-run -a julia --color=yes --project=docs'
 
@@ -77,6 +77,10 @@ $julia -e '
   Pkg.add("PyCall"); Pkg.build("PyCall"; verbose=true)
 '
 
+export JULIA_PYTHONCALL_EXE=$($julia -e 'import Conda; print(joinpath(Conda.BINDIR, "python"))')
+export JULIA_CONDAPKG_EXE=$($julia -e 'import Conda; print(Conda.CONDA_EXE)')
+export JULIA_CONDAPKG_BACKEND=Null
+
 echo "== build documentation for $GITHUB_REPOSITORY@$GITHUB_REF, triggerd by $GITHUB_ACTOR on $GITHUB_EVENT_NAME =="
 if [ "$GITHUB_REPOSITORY" == 'JuliaPlots/PlotDocs.jl' ]; then
   $julia -e 'using Pkg; Pkg.add(PackageSpec(name="Plots", rev="master"))'

docs/make.jl

@@ -813,6 +813,18 @@ function main()
         end
     end
 
+    # postprocess temporary work dir
+    src = basename(SRC_DIR)
+    for file ∈ glob("*/index.html", joinpath(@__DIR__, "build"))
+        lines = readlines(file; keep=true)
+        any((occursin("blob/master/docs", line) for line ∈ lines)) || continue
+        open(file, "w") do io
+            for line ∈ lines
+                write(io, replace(line, "blob/master/docs/$work" => "blob/master/docs/$src"))
+            end
+        end
+    end
+
     @info "deploydocs"
     deploydocs(
         repo = "github.com/JuliaPlots/PlotDocs.jl.git",

docs/src/backends.md

@@ -50,6 +50,22 @@ For those who haven't had the pleasure of hacking on 15 different plotting APIs:
 However, you will probably have a hard time choosing the right backend for your task at hand.
 This document is meant to be a guide and introduction to make that choice.
 
+# Persistent backend selection
+
+Plots uses the [Preferences](https://github.com/JuliaPackaging/Preferences.jl) mechanism to make the default backend choice persistent across julia restart.
+
+```julia
+$ JULIA_PKG_PRECOMPILE_AUTO=0 julia -e 'import Plots; Plots.set_default_backend!(:pythonplot)'
+$ julia  # restart, show persistent mode
+julia> using Plots
+[ Info: Precompiling Plots [91a5bcdd-55d7-5caf-9e0b-520d859cae80]
+[ Info: PythonPlot  # precompiles for this backend
+julia> plot(1:2) |> display  # uses `PythonPlot` by default
+```
+
+You can clear preferences with `Plots.set_default_backend!()`.
+Alternatively, one can use the environment variable `PLOTS_DEFAULT_BACKEND` to select the default backend (but this will need to trigger manual precompilation using `Base.compilecache(Plots)`).
+
 # At a glance
 
 My favorites: `GR` for speed, `Plotly(JS)` for interactivity, `UnicodePlots` for REPL/SSH and `PythonPlot` otherwise.