Fix the deploy_folder fallbacks and the docstring for deploy_folder

CHANGELOG.md

@@ -8,7 +8,7 @@
 
 * ![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. ([#1307][github-1307], [#1310][github-1310])
+* ![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. ([#1307][github-1307], [#1310][github-1310], [#1315][github-1315])
 
 * ![Bugfix][badge-bugfix] `Deps.pip` is again a closure and gets executed during the `deploydocs` call, not before it. ([#1240][github-1240])
 
@@ -572,6 +572,7 @@
 [github-1311]: https://github.com/JuliaDocs/Documenter.jl/pull/1311
 [github-1307]: https://github.com/JuliaDocs/Documenter.jl/pull/1307
 [github-1310]: https://github.com/JuliaDocs/Documenter.jl/pull/1310
+[github-1315]: https://github.com/JuliaDocs/Documenter.jl/pull/1315
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

docs/src/man/hosting.md

@@ -418,6 +418,7 @@ your own by following the simple interface described below.
 ```@docs
 Documenter.DeployConfig
 Documenter.deploy_folder
+Documenter.DeployDecision
 Documenter.authentication_method
 Documenter.authenticated_repo_url
 Documenter.documenter_key

src/deployconfig.jl

@@ -7,6 +7,19 @@ Abstract type which new deployment configs should be subtypes of.
 """
 abstract type DeployConfig end
 
+"""
+    DeployDecision(; kwargs...)
+
+Struct containing information about the decision to deploy or not deploy.
+
+# Arguments
+
+- `all_ok::Bool` - Should documentation be deployed?
+- `branch::String` - The branch to which documentation should be pushed
+- `is_preview::Bool` - Is this documentation build a pull request?
+- `repo::String` - The repo to which documentation should be pushed
+- `subfolder::String` - The subfolder to which documentation should be pushed
+"""
 Base.@kwdef struct DeployDecision
     all_ok::Bool
     branch::String = ""
@@ -45,8 +58,7 @@ end
 """
     Documenter.deploy_folder(cfg::DeployConfig; repo, devbranch, push_preview, devurl, kwargs...)
 
-Return the folder where the documentation should be deployed to, or `nothing`
-if the current build should not deploy.
+Return a `DeployDecision`.
 This function is called with the `repo`, `devbranch`, `push_preview` and `devurl`
 arguments from [`deploydocs`](@ref).
 
@@ -57,11 +69,11 @@ arguments from [`deploydocs`](@ref).
 """
 function deploy_folder(cfg::DeployConfig; kwargs...)
     @warn "Documenter.deploy_folder(::$(typeof(cfg)); kwargs...) not implemented. Skipping deployment."
-    return nothing
+    return DeployDecision(; all_ok = false)
 end
 function deploy_folder(::Nothing; kwargs...)
     @warn "Documenter could not auto-detect the building environment Skipping deployment."
-    return nothing
+    return DeployDecision(; all_ok = false)
 end
 
 @enum AuthenticationMethod SSH HTTPS

test/deployconfig.jl

@@ -300,8 +300,8 @@ struct BrokenConfig <: Documenter.DeployConfig end
         @test d.all_ok
         @test d.subfolder == "v1.2.3"
         cfg = BrokenConfig()
-        @test (@test_logs (:warn, r"Documenter\.deploy_folder\(::BrokenConfig; kwargs\.\.\.\) not implemented") Documenter.deploy_folder(cfg)) === nothing
-        @test (@test_logs (:warn, r"Documenter could not auto-detect") Documenter.deploy_folder(nothing)) === nothing
+        @test (@test_logs (:warn, r"Documenter\.deploy_folder\(::BrokenConfig; kwargs\.\.\.\) not implemented") Documenter.deploy_folder(cfg)) == Documenter.DeployDecision(; all_ok = false)
+        @test (@test_logs (:warn, r"Documenter could not auto-detect") Documenter.deploy_folder(nothing)) == Documenter.DeployDecision(; all_ok = false)
 end end
 
 @testset "Autodetection of deploy system" begin