Work around JuliaLang/Pkg.jl#2219 (#324)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.github/workflows/docs.yml

@@ -22,4 +22,5 @@ jobs:
           GKSwstype: nul # turn off GR's interactive plotting for notebooks
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+          JULIA_DEBUG: Documenter # Print `@debug` statements (https://github.com/JuliaDocs/Documenter.jl/issues/955)
         run: julia --project=docs/ docs/make.jl

docs/Manifest.toml

@@ -2,9 +2,9 @@
 
 [[AbstractFFTs]]
 deps = ["LinearAlgebra"]
-git-tree-sha1 = "051c95d6836228d120f5f4b984dd5aba1624f716"
+git-tree-sha1 = "485ee0867925449198280d4af84bdb46a2a404d0"
 uuid = "621f4979-c628-5d54-868e-fcf4e3e8185c"
-version = "0.5.0"
+version = "1.0.1"
 
 [[ArgTools]]
 uuid = "0dad84c5-d112-42e6-8d28-ef12dabb789f"
@@ -73,19 +73,19 @@ version = "0.8.5"
 
 [[Documenter]]
 deps = ["Base64", "Dates", "DocStringExtensions", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
-git-tree-sha1 = "621850838b3e74dd6dd047b5432d2e976877104e"
+git-tree-sha1 = "47f13b6305ab195edb73c86815962d84e31b0f48"
 uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-version = "0.27.2"
+version = "0.27.3"
 
 [[Downloads]]
 deps = ["ArgTools", "LibCURL", "NetworkOptions"]
 uuid = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 
 [[FillArrays]]
 deps = ["LinearAlgebra", "Random", "SparseArrays"]
-git-tree-sha1 = "31939159aeb8ffad1d4d8ee44d07f8558273120a"
+git-tree-sha1 = "a603e79b71bb3c1efdb58f0ee32286efe2d1a255"
 uuid = "1a297f60-69ca-5386-bcde-b61e274b549b"
-version = "0.11.7"
+version = "0.11.8"
 
 [[Functors]]
 deps = ["MacroTools"]
@@ -187,9 +187,9 @@ uuid = "14a3606d-f60d-562e-9121-12d972cd8159"
 
 [[NamedDims]]
 deps = ["AbstractFFTs", "LinearAlgebra", "Pkg", "Requires", "Statistics"]
-git-tree-sha1 = "e91d3ee8ac1514651b6e85686ca31257d17b1eb2"
+git-tree-sha1 = "572b7af3ee53328eec29392d3b133804925595a1"
 uuid = "356022a1-0364-5f58-8944-0da4b18d706f"
-version = "0.2.33"
+version = "0.2.34"
 
 [[NetworkOptions]]
 uuid = "ca575930-c2e3-43a9-ace4-1e988b2c1908"

docs/Project.toml

@@ -7,6 +7,6 @@ PDMats = "90014a1f-27ba-587c-ab20-58faa44d9150"
 [compat]
 Documenter = "0.27"
 KernelFunctions = "0.10"
-PDMats = "0.11"
 Kronecker = "0.4"
+PDMats = "0.11"
 julia = "1.3"

docs/literate.jl

@@ -1,14 +1,15 @@
-# Retrieve filename of literate script
+# Retrieve name of example and output directory
 if length(ARGS) != 2
-    error("please specify the literate script and the output directory")
+    error("please specify the name of the example and the output directory")
 end
-const SCRIPTJL = ARGS[1]
+const EXAMPLE = ARGS[1]
 const OUTDIR = ARGS[2]
 
 # Activate environment
-using Pkg: Pkg
-Pkg.activate(dirname(SCRIPTJL))
 # Note that each example's Project.toml must include Literate as a dependency
+using Pkg: Pkg
+const EXAMPLEPATH = joinpath(@__DIR__, "..", "examples", EXAMPLE)
+Pkg.activate(EXAMPLEPATH)
 Pkg.instantiate()
 using Literate: Literate
 
@@ -38,10 +39,10 @@ function preprocess(content)
 end
 
 # Convert to markdown and notebook
-name = basename(dirname(realpath(SCRIPTJL)))
+const SCRIPTJL = joinpath(EXAMPLEPATH, "script.jl")
 Literate.markdown(
-    SCRIPTJL, OUTDIR; name=name, documenter=false, execute=true, preprocess=preprocess
+    SCRIPTJL, OUTDIR; name=EXAMPLE, documenter=false, execute=true, preprocess=preprocess
 )
 Literate.notebook(
-    SCRIPTJL, OUTDIR; name=name, documenter=false, execute=true, preprocess=preprocess
+    SCRIPTJL, OUTDIR; name=EXAMPLE, documenter=false, execute=true, preprocess=preprocess
 )

docs/make.jl

@@ -1,24 +1,36 @@
 ### Process examples
-const EXAMPLES_SRC = joinpath(@__DIR__, "..", "examples")
-const EXAMPLES_OUT = joinpath(@__DIR__, "src", "examples")
-const LITERATEJL = joinpath(@__DIR__, "literate.jl")
-
 # Always rerun examples
+const EXAMPLES_OUT = joinpath(@__DIR__, "src", "examples")
 ispath(EXAMPLES_OUT) && rm(EXAMPLES_OUT; recursive=true)
 mkpath(EXAMPLES_OUT)
 
+# Install and precompile all packages
+# Workaround for https://github.com/JuliaLang/Pkg.jl/issues/2219
+examples = filter!(isdir, readdir(joinpath(@__DIR__, "..", "examples"); join=true))
+let script = "using Pkg; Pkg.activate(ARGS[1]); Pkg.instantiate()"
+    for example in examples
+        if !success(`$(Base.julia_cmd()) -e $script $example`)
+            error(
+                "project environment of example ",
+                basename(example),
+                " could not be instantiated",
+            )
+        end
+    end
+end
 # Run examples asynchronously
-processes = map(filter!(isdir, readdir(EXAMPLES_SRC; join=true))) do example
-    scriptjl = joinpath(example, "script.jl")
-    return run(
-        pipeline(
-            `$(Base.julia_cmd()) $LITERATEJL $scriptjl $EXAMPLES_OUT`;
-            stdin=devnull,
-            stdout=devnull,
-            stderr=stderr,
-        );
-        wait=false,
-    )::Base.Process
+processes = let literatejl = joinpath(@__DIR__, "literate.jl")
+    map(examples) do example
+        return run(
+            pipeline(
+                `$(Base.julia_cmd()) $literatejl $(basename(example)) $EXAMPLES_OUT`;
+                stdin=devnull,
+                stdout=devnull,
+                stderr=stderr,
+            );
+            wait=false,
+        )::Base.Process
+    end
 end
 
 # Check that all examples were run successfully
@@ -30,11 +42,6 @@ using Documenter
 using KernelFunctions
 using PDMats, Kronecker  # we have to load all optional packages to generate the full API documentation
 
-# Print `@debug` statements (https://github.com/JuliaDocs/Documenter.jl/issues/955)
-if haskey(ENV, "GITHUB_ACTIONS")
-    ENV["JULIA_DEBUG"] = "Documenter"
-end
-
 # Doctest setup
 DocMeta.setdocmeta!(
     KernelFunctions,

examples/README.md

@@ -28,7 +28,7 @@ julia> Literate.notebook("script.jl", "output_directory")
 ```
 (see the [Literate.jl docs](https://fredrikekre.github.io/Literate.jl/v2/) for additional options) or run
 ```shell
-julia docs/literate.jl examples/myexample/script.jl output_directory
+julia docs/literate.jl myexample output_directory
 ```
 which also executes the code and generates embedded plots etc. in the same way as in building the KernelFunctions documentation.