Allow "deploying" to a tarball (#1865)

CHANGELOG.md

@@ -19,6 +19,7 @@
   - highlight.js has been updated from `v11.0.1` to `v11.5.1`.
   - KaTeX has been updated from `v0.13.11` to `v0.13.24`.
 
+* ![Experimental][badge-experimental] `deploydocs` now supports "deploying to tarball" (rather than pushing to the `gh-pages` branch) via the undocumented experiments `archive` keyword. ([#1865][github-1865])
 * ![Bugfix][badge-bugfix] When including docstrings for an alias, Documenter now correctly tries to include the exactly matching docstring first, before checking for signature subtypes. ([#1842][github-1842])
 * ![Bugfix][badge-bugfix] When checking for missing docstrings, Documenter now correctly handles docstrings for methods that extend bindings from other modules that have not been imported into the current module. ([#1695][github-1695], [#1857][github-1857], [#1861][github-1861])
 * ![Bugfix][badge-bugfix] By overriding `GIT_TEMPLATE_DIR`, `git` no longer picks up arbitrary user templates and hooks when internally called by Documenter. ([#1862][github-1862])
@@ -1085,6 +1086,7 @@
 [github-1857]: https://github.com/JuliaDocs/Documenter.jl/issues/1857
 [github-1861]: https://github.com/JuliaDocs/Documenter.jl/pull/1861
 [github-1862]: https://github.com/JuliaDocs/Documenter.jl/pull/1862
+[github-1865]: https://github.com/JuliaDocs/Documenter.jl/pull/1865
 <!-- end of issue link definitions -->
 
 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079

src/Documenter.jl

@@ -526,13 +526,22 @@ function deploydocs(;
         forcepush::Bool = false,
         deploy_config = auto_detect_deploy_system(),
         push_preview::Bool = false,
+
+        archive = nothing, # experimental and undocumented
     )
 
     # Try to figure out default branch (see #1443 and #1727)
     if devbranch === nothing
         devbranch = Utilities.git_remote_head_branch("deploydocs(devbranch = ...)", root)
     end
 
+    if !isnothing(archive)
+        # If archive is a relative path, we'll make it relative to the make.jl
+        # directory (e.g. docs/)
+        archive = joinpath(root, archive)
+        ispath(archive) && error("Output archive exists: $archive")
+    end
+
     deploy_decision = deploy_folder(deploy_config;
                                     branch=branch,
                                     branch_previews=branch_previews,
@@ -587,7 +596,7 @@ function deploydocs(;
                     branch=deploy_branch, dirname=dirname, target=target,
                     sha=sha, deploy_config=deploy_config, subfolder=deploy_subfolder,
                     devurl=devurl, versions=versions, forcepush=forcepush,
-                    is_preview=deploy_is_preview,
+                    is_preview=deploy_is_preview, archive=archive,
                 )
             end
         end
@@ -608,7 +617,7 @@ function git_push(
         root, temp, repo;
         branch="gh-pages", dirname="", target="site", sha="", devurl="dev",
         versions, forcepush=false, deploy_config, subfolder,
-        is_preview::Bool = false,
+        is_preview::Bool = false, archive,
     )
     dirname = isempty(dirname) ? temp : joinpath(temp, dirname)
     isdir(dirname) || mkpath(dirname)
@@ -693,7 +702,11 @@ function git_push(
         # Add, commit, and push the docs to the remote.
         run(`$(git()) add -A .`)
         if !success(`$(git()) diff --cached --exit-code`)
-            if forcepush
+            if !isnothing(archive)
+                run(`$(git()) commit -m "build based on $sha"`)
+                @info "Skipping push and writing repository to an archive" archive
+                run(`$(git()) archive -o $(archive) HEAD`)
+            elseif forcepush
                 run(`$(git()) commit --amend --date=now -m "build based on $sha"`)
                 run(`$(git()) push -fq upstream HEAD:$branch`)
             else

test/deploydocs.jl

@@ -0,0 +1,73 @@
+isdefined(@__MODULE__, :TestUtilities) || include("TestUtilities.jl")
+using Documenter: Documenter, deploydocs
+using Documenter.Utilities: git
+using Test, ..TestUtilities
+
+struct TestDeployConfig <: Documenter.DeployConfig
+    repo_path :: String
+    subfolder :: String
+end
+function Documenter.deploy_folder(c::TestDeployConfig; branch, repo, kwargs...)
+    Documenter.DeployDecision(; all_ok = true, subfolder = c.subfolder, branch, repo)
+end
+Documenter.authentication_method(::TestDeployConfig) = Documenter.HTTPS
+Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path
+
+@testset "deploydocs" begin
+    mktempdir() do dir
+        cd(dir) do
+            mkdir("repo")
+            run(`$(git()) -C repo init -q --bare`)
+            full_repo_path = joinpath(pwd(), "repo")
+            # Pseudo makedocs products in build/
+            mkdir("build")
+            write("build/page.html", "...")
+            # Create gh-pages and deploy dev/
+            @quietly deploydocs(
+                root = pwd(),
+                deploy_config = TestDeployConfig(full_repo_path, "dev"),
+                repo = full_repo_path,
+                devbranch = "master",
+            )
+            # Deploy 1.0.0 tag
+            @quietly deploydocs(
+                root = pwd(),
+                deploy_config = TestDeployConfig(full_repo_path, "1.0.0"),
+                repo = full_repo_path,
+                devbranch = "master",
+            )
+            # Deploy 1.1.0 tag
+            @quietly deploydocs(
+                root = pwd(),
+                deploy_config = TestDeployConfig(full_repo_path, "1.1.0"),
+                repo = full_repo_path,
+                devbranch = "master",
+            )
+            # Deploy 2.0.0 tag, but into an archive (so nothing pushed to gh-pages)
+            @quietly deploydocs(
+                root = pwd(),
+                deploy_config = TestDeployConfig(full_repo_path, "2.0.0"),
+                repo = full_repo_path,
+                devbranch = "master",
+                archive = joinpath(pwd(), "ghpages.tar.gz"),
+            )
+            # Check what we have in gh-pages now:
+            run(`$(git()) clone -q -b gh-pages $(full_repo_path) worktree`)
+            @test isfile(joinpath("worktree", "index.html"))
+            @test isfile(joinpath("worktree", "versions.js"))
+            for d in ["dev", "v1.0.0", "v1.1.0"]
+                @test isfile(joinpath("worktree", d, "page.html"))
+                @test isfile(joinpath("worktree", d, "siteinfo.js"))
+            end
+            @test islink(joinpath("worktree", "v1"))
+            @test islink(joinpath("worktree", "v1.0"))
+            @test islink(joinpath("worktree", "v1.1"))
+            @test islink(joinpath("worktree", "stable"))
+            # And make sure that archived option didn't modify gh-pages
+            @test ! ispath(joinpath("worktree", "2.0.0"))
+            @test ! ispath(joinpath("worktree", "v2.0"))
+            @test ! ispath(joinpath("worktree", "v2"))
+            @test isfile("ghpages.tar.gz")
+        end
+    end
+end

test/runtests.jl

@@ -53,6 +53,7 @@ include("TestUtilities.jl"); using .TestUtilities
 
     # Deployment configurations
     include("deployconfig.jl")
+    include("deploydocs.jl")
 
     # Mock package docs.
     include("examples/tests.jl")