Use a docs environment

This should decrease the time required to build the docs on CI, and
follows the "best practices" that e.g., JuliaHub expects.

Author: goerz

.github/workflows/CI.yml

@@ -60,6 +60,14 @@ jobs:
         with:
           files: lcov.info
           token: ${{ secrets.CODECOV_TOKEN }}
+      - name: Save Julia depot cache on cancel or failure
+        id: julia-cache-save
+        if: cancelled() || failure()
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ${{ steps.julia-cache.outputs.cache-paths }}
+          key: ${{ steps.julia-cache.outputs.cache-key }}
   docs:
     name: Documentation
     runs-on: ubuntu-latest
@@ -78,10 +86,10 @@ jobs:
           wget https://raw.githubusercontent.com/JuliaQuantumControl/JuliaQuantumControl/master/scripts/installorg.jl
           install -m 600 -D /dev/null ~/.ssh/known_hosts
           ssh-keyscan -H github.com > ~/.ssh/known_hosts
-          julia --project=test -e 'include("installorg.jl"); installorg(; github="develop")'
+          julia --project=docs -e 'include("installorg.jl"); installorg(; github="develop")'
           # installing in develop mode enables proper "source" links in subpackage APIs
       - name: "Build documentation"
-        run: julia --project=test docs/make.jl
+        run: julia --project=docs docs/make.jl
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
@@ -96,6 +104,14 @@ jobs:
           path: |
             README.md
             ./docs.zip
+      - name: Save Julia depot cache on cancel or failure
+        id: julia-cache-save
+        if: cancelled() || failure()
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ${{ steps.julia-cache.outputs.cache-paths }}
+          key: ${{ steps.julia-cache.outputs.cache-key }}
   codestyle:
     name: Codestyle
     runs-on: ubuntu-latest

.gitignore

@@ -4,7 +4,6 @@
 /Manifest.toml
 /test/Manifest.toml
 /docs/Manifest.toml
-/docs/Project.toml
 /docs/build/
 /gh-pages/
 /.JuliaFormatter.toml

Makefile

@@ -30,13 +30,16 @@ test/Manifest.toml: test/Project.toml ../scripts/installorg.jl
 	$(JULIA) --project=test ../scripts/installorg.jl
 	@touch $@
 
+docs/Manifest.toml: docs/Project.toml ../scripts/installorg.jl
+	$(JULIA) --project=docs ../scripts/installorg.jl
+	@touch $@
 
 devrepl:  ## Start an interactive REPL for testing and building documentation
 	$(JULIA) --project=test --banner=no --startup-file=yes -i devrepl.jl
 
 
-docs: test/Manifest.toml  ## Build the documentation
-	$(JULIA) --project=test docs/make.jl
+docs: docs/Manifest.toml  ## Build the documentation
+	$(JULIA) --project=docs docs/make.jl
 	@echo "Done. Consider using 'make devrepl'"
 
 servedocs: test/Manifest.toml  ## Build (auto-rebuild) and serve documentation at PORT=8000

docs/Project.toml

@@ -0,0 +1,16 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+GRAPE = "6b52fcaf-80fe-489a-93e9-9f92080510be"
+Krotov = "b05dcdc7-62f6-4360-bf2c-0898bba419de"
+OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
+QuantumControl = "8a270532-f23f-47a8-83a9-b33d10cad486"
+QuantumPropagators = "7bf12567-5742-4b91-a078-644e72a65fc1"
+
+[sources]
+QuantumControl = {path = ".."}
+
+[compat]
+Documenter = "1.4"
+julia = "1.11"

docs/make.jl

@@ -1,4 +1,5 @@
 using Pkg
+Pkg.develop(path=joinpath(@__DIR__, ".."))
 
 using Documenter
 using QuantumPropagators
@@ -128,5 +129,4 @@ makedocs(;
 )
 
 println("Finished makedocs")
-
-deploydocs(; repo="github.com/JuliaQuantumControl/QuantumControl.jl")
+deploydocs(; repo="github.com/JuliaQuantumControl/QuantumControl.jl", push_preview=true)

test/Project.toml

@@ -48,6 +48,9 @@ UnPack = "3a884ed6-31ef-47d7-9d2a-63182c4928ed"
 UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
+[sources]
+QuantumControl = {path = ".."}
+
 [compat]
 Documenter = "1.4"
 julia = "1.9"

test/clean.jl

@@ -38,7 +38,6 @@ function clean(; distclean=false, _exit=true)
     for folder in ["", "docs", "test"]
         _push!(DISTCLEAN, joinpath(joinpath(ROOT, folder), "Manifest.toml"))
     end
-    _push!(DISTCLEAN, joinpath(ROOT, "docs", "Project.toml"))
     _push!(DISTCLEAN, joinpath(ROOT, "docs", "src", "examples", ".ipynb_checkpoints"))
     _push!(DISTCLEAN, joinpath(ROOT, ".JuliaFormatter.toml"))
     ###########################################################################