Add support for pushing PR previews to a different branch and/or diff…

…erent repo (#1307)

CHANGELOG.md

@@ -8,6 +8,8 @@
 
 * ![Enhancement][badge-enhancement] When deploying on CI with `deploydocs`, the build information in the version number (i.e. what comes after `+`) is now discarded when determining the destination directory. This allows custom tags to be used to fix documentation build and deployment issues for versions that have already been registered. ([#1298][github-1298])
 
+* ![Enhancement][badge-enhancement] You can now optionally choose to push pull request preview builds to a different branch and/or different repository than the main docs builds, by setting the optional `branch_previews` and/or `repo_previews` keyword arguments to the `deploydocs` function. Also, you can now optionally choose to use a different SSH key for preview builds, by setting the optional `DOCUMENTER_KEY_PREVIEWS` environment variable; if the `DOCUMENTER_KEY_PREVIEWS` environment variable is not set, then the regular `DOCUMENTER_KEY` environment variable will be used.
+
 * ![Bugfix][badge-bugfix] `Deps.pip` is again a closure and gets executed during the `deploydocs` call, not before it. ([#1240][github-1240])
 
 ## Version `v0.24.10`

docs/src/man/hosting.md

@@ -421,6 +421,7 @@ Documenter.deploy_folder
 Documenter.authentication_method
 Documenter.authenticated_repo_url
 Documenter.documenter_key
+Documenter.documenter_key_previews
 Documenter.Travis
 Documenter.GitHubActions
 ```

src/Documenter.jl

@@ -305,7 +305,9 @@ include("deployconfig.jl")
         devbranch = "master",
         devurl = "dev",
         versions = ["stable" => "v^", "v#.#", devurl => devurl],
-        push_preview = false
+        push_preview    = false,
+        repo_previews   = repo,
+        branch_previews = branch,
     )
 
 Converts markdown files generated by [`makedocs`](@ref) to HTML and pushes them to `repo`.
@@ -394,6 +396,12 @@ the generated html. The following entries are valid in the `versions` vector:
 **`push_preview`** a boolean that specifies if preview documentation should be
 deployed from pull requests or not.
 
+**`branch_previews`** is the branch to which pull request previews are deployed.
+It defaults to the value of `branch`.
+
+**`repo_previews`** is the remote repository to which pull request previews are
+deployed. It defaults to the value of `repo`.
+
 # Releases vs development branches
 
 [`deploydocs`](@ref) will automatically figure out whether it is deploying the documentation
@@ -418,6 +426,9 @@ function deploydocs(;
         repo   = error("no 'repo' keyword provided."),
         branch = "gh-pages",
 
+        repo_previews   = repo,
+        branch_previews = branch,
+
         deps   = nothing,
         make   = nothing,
 
@@ -429,8 +440,20 @@ function deploydocs(;
         push_preview::Bool = false,
     )
 
-    subfolder = deploy_folder(deploy_config; repo=repo, devbranch=devbranch, push_preview=push_preview, devurl=devurl)
-    if subfolder !== nothing
+    deploy_decision = deploy_folder(deploy_config;
+                                    branch=branch,
+                                    branch_previews=branch_previews,
+                                    devbranch=devbranch,
+                                    devurl=devurl,
+                                    push_preview=push_preview,
+                                    repo=repo,
+                                    repo_previews=repo_previews)
+    if deploy_decision.all_ok
+        deploy_branch = deploy_decision.branch
+        deploy_repo = deploy_decision.repo
+        deploy_subfolder = deploy_decision.subfolder
+        deploy_is_preview = deploy_decision.is_preview
+
         # Add local bin path if needed.
         Deps.updatepath!()
         # Install dependencies when applicable.
@@ -461,13 +484,14 @@ function deploydocs(;
                 @debug "running extra build steps."
                 make()
             end
-            @debug "pushing new documentation to remote: '$repo:$branch'."
+            @debug "pushing new documentation to remote: '$deploy_branch:$branch'."
             mktempdir() do temp
                 git_push(
-                    root, temp, repo;
-                    branch=branch, dirname=dirname, target=target,
-                    sha=sha, deploy_config=deploy_config, subfolder=subfolder,
+                    root, temp, deploy_repo;
+                    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,
                 )
             end
         end
@@ -488,6 +512,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,
     )
     dirname = isempty(dirname) ? temp : joinpath(temp, dirname)
     isdir(dirname) || mkpath(dirname)
@@ -573,7 +598,12 @@ function git_push(
 
         keyfile = abspath(joinpath(root, ".documenter"))
         try
-            write(keyfile, base64decode(documenter_key(deploy_config)))
+            if is_preview
+                keycontent = documenter_key_previews(deploy_config)
+            else
+                keycontent = documenter_key(deploy_config)
+            end
+            write(keyfile, base64decode(keycontent))
         catch e
             @error """
             Documenter failed to decode the DOCUMENTER_KEY environment variable.

src/deployconfig.jl

@@ -7,6 +7,14 @@ Abstract type which new deployment configs should be subtypes of.
 """
 abstract type DeployConfig end
 
+Base.@kwdef struct DeployDecision
+    all_ok::Bool
+    branch::String = ""
+    is_preview::Bool = false
+    repo::String = ""
+    subfolder::String = ""
+end
+
 """
     Documenter.documenter_key(cfg::DeployConfig)
 
@@ -20,6 +28,20 @@ function documenter_key(::DeployConfig)
     return ENV["DOCUMENTER_KEY"]
 end
 
+"""
+    Documenter.documenter_key_previews(cfg::DeployConfig)
+
+Return the Base64-encoded SSH private key for the repository.
+Uses the `DOCUMENTER_KEY_PREVIEWS` environment variable if it is defined,
+otherwise uses the `DOCUMENTER_KEY` environment variable.
+
+This method must be supported by configs that push with SSH, see
+[`Documenter.authentication_method`](@ref).
+"""
+function documenter_key_previews(cfg::DeployConfig)
+    return get(ENV, "DOCUMENTER_KEY_PREVIEWS", documenter_key(cfg))
+end
+
 """
     Documenter.deploy_folder(cfg::DeployConfig; repo, devbranch, push_preview, devurl, kwargs...)
 
@@ -125,7 +147,15 @@ function Travis()
 end
 
 # Check criteria for deployment
-function deploy_folder(cfg::Travis; repo, devbranch, push_preview, devurl, kwargs...)
+function deploy_folder(cfg::Travis;
+                       repo,
+                       repo_previews = repo,
+                       branch = "gh-pages",
+                       branch_previews = branch,
+                       devbranch,
+                       push_preview,
+                       devurl,
+                       kwargs...)
     io = IOBuffer()
     all_ok = true
     ## Determine build type; release, devbranch or preview
@@ -151,6 +181,9 @@ function deploy_folder(cfg::Travis; repo, devbranch, push_preview, devurl, kwarg
         tag_ok = tag_nobuild !== nothing
         all_ok &= tag_ok
         println(io, "- $(marker(tag_ok)) ENV[\"TRAVIS_TAG\"] contains a valid VersionNumber")
+        deploy_branch = branch
+        deploy_repo = repo
+        is_preview = false
         ## Deploy to folder according to the tag
         subfolder = tag_nobuild
     elseif build_type === :devbranch
@@ -162,6 +195,9 @@ function deploy_folder(cfg::Travis; repo, devbranch, push_preview, devurl, kwarg
         branch_ok = !isempty(cfg.travis_tag) || cfg.travis_branch == devbranch
         all_ok &= branch_ok
         println(io, "- $(marker(branch_ok)) ENV[\"TRAVIS_BRANCH\"] matches devbranch=\"$(devbranch)\"")
+        deploy_branch = branch
+        deploy_repo = repo
+        is_preview = false
         ## Deploy to deploydocs devurl kwarg
         subfolder = devurl
     else # build_type === :preview
@@ -172,6 +208,9 @@ function deploy_folder(cfg::Travis; repo, devbranch, push_preview, devurl, kwarg
         btype_ok = push_preview
         all_ok &= btype_ok
         println(io, "- $(marker(btype_ok)) `push_preview` keyword argument to deploydocs is `true`")
+        deploy_branch = branch_previews
+        deploy_repo = repo_previews
+        is_preview = true
         ## deploy to previews/PR
         subfolder = "previews/PR$(something(pr_number, 0))"
     end
@@ -185,7 +224,15 @@ function deploy_folder(cfg::Travis; repo, devbranch, push_preview, devurl, kwarg
     println(io, "- $(marker(type_ok)) ENV[\"TRAVIS_EVENT_TYPE\"]=\"$(cfg.travis_event_type)\" is not \"cron\"")
     print(io, "Deploying: $(marker(all_ok))")
     @info String(take!(io))
-    return all_ok ? subfolder : nothing
+    if all_ok
+        return DeployDecision(; all_ok = true,
+                                branch = deploy_branch,
+                                is_preview = is_preview,
+                                repo = deploy_repo,
+                                subfolder = subfolder)
+    else
+        return DeployDecision(; all_ok = false)
+    end
 end
 
 
@@ -228,7 +275,15 @@ function GitHubActions()
 end
 
 # Check criteria for deployment
-function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl, kwargs...)
+function deploy_folder(cfg::GitHubActions;
+                       repo,
+                       repo_previews = repo,
+                       branch = "gh-pages",
+                       branch_previews = branch,
+                       devbranch,
+                       push_preview,
+                       devurl,
+                       kwargs...)
     io = IOBuffer()
     all_ok = true
     ## Determine build type
@@ -255,6 +310,9 @@ function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl
         tag_ok = tag_nobuild !== nothing
         all_ok &= tag_ok
         println(io, "- $(marker(tag_ok)) ENV[\"GITHUB_REF\"]=\"$(cfg.github_ref)\" contains a valid VersionNumber")
+        deploy_branch = branch
+        deploy_repo = repo
+        is_preview = false
         ## Deploy to folder according to the tag
         subfolder = m === nothing ? nothing : tag_nobuild
     elseif build_type === :devbranch
@@ -267,6 +325,9 @@ function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl
         branch_ok = m === nothing ? false : String(m.captures[1]) == devbranch
         all_ok &= branch_ok
         println(io, "- $(marker(branch_ok)) ENV[\"GITHUB_REF\"] matches devbranch=\"$(devbranch)\"")
+        deploy_branch = branch
+        deploy_repo = repo
+        is_preview = false
         ## Deploy to deploydocs devurl kwarg
         subfolder = devurl
     else # build_type === :preview
@@ -278,6 +339,9 @@ function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl
         btype_ok = push_preview
         all_ok &= btype_ok
         println(io, "- $(marker(btype_ok)) `push_preview` keyword argument to deploydocs is `true`")
+        deploy_branch = branch_previews
+        deploy_repo = repo_previews
+        is_preview = true
         ## deploydocs to previews/PR
         subfolder = "previews/PR$(something(pr_number, 0))"
     end
@@ -299,7 +363,15 @@ function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl
     end
     print(io, "Deploying: $(marker(all_ok))")
     @info String(take!(io))
-    return all_ok ? subfolder : nothing
+    if all_ok
+        return DeployDecision(; all_ok = true,
+                                branch = deploy_branch,
+                                is_preview = is_preview,
+                                repo = deploy_repo,
+                                subfolder = subfolder)
+    else
+        return DeployDecision(; all_ok = false)
+    end
 end
 
 function authentication_method(::GitHubActions)