From bd1e34468b674fcc57f4833e75d48fb4bfc3b010 Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Tue, 28 Jun 2022 19:04:20 +1200 Subject: [PATCH 1/5] Add option to deploy to tarball --- src/Documenter.jl | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index c801d279c8..2e0c69da57 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -526,6 +526,8 @@ 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) @@ -533,6 +535,13 @@ function deploydocs(; 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 From d3ea1f4339be172b553062fb163e7850f500828d Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Thu, 30 Jun 2022 14:45:06 +1200 Subject: [PATCH 2/5] test --- docs/make.jl | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index fd3b01fa96..c324cd8567 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -80,15 +80,16 @@ if "pdf" in ARGS end end deploydocs( - repo = "github.com/JuliaDocs/Documenter.jl.git", + repo = "github.com/fredrikekre/Documenter.jl.git", target = "pdf/build-pdf/commit", branch = "gh-pages-pdf", forcepush = true, ) else deploydocs( - repo = "github.com/JuliaDocs/Documenter.jl.git", + repo = "github.com/fredrikekre/Documenter.jl.git", target = "build", push_preview = true, + archive = "ghpages.tar.gz", ) end From 2ad8ef0d47a28ed7aa6221c90b04930195e9fb47 Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Wed, 6 Jul 2022 18:20:35 +1200 Subject: [PATCH 3/5] Revert "test" This reverts commit d3ea1f4339be172b553062fb163e7850f500828d. --- docs/make.jl | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index c324cd8567..fd3b01fa96 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -80,16 +80,15 @@ if "pdf" in ARGS end end deploydocs( - repo = "github.com/fredrikekre/Documenter.jl.git", + repo = "github.com/JuliaDocs/Documenter.jl.git", target = "pdf/build-pdf/commit", branch = "gh-pages-pdf", forcepush = true, ) else deploydocs( - repo = "github.com/fredrikekre/Documenter.jl.git", + repo = "github.com/JuliaDocs/Documenter.jl.git", target = "build", push_preview = true, - archive = "ghpages.tar.gz", ) end From 921e6c70c422a4411fcc27ca3b5922dd813f2a65 Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Wed, 6 Jul 2022 19:57:42 +1200 Subject: [PATCH 4/5] add tests for deploydocs --- test/deploydocs.jl | 73 ++++++++++++++++++++++++++++++++++++++++++++++ test/runtests.jl | 1 + 2 files changed, 74 insertions(+) create mode 100644 test/deploydocs.jl diff --git a/test/deploydocs.jl b/test/deploydocs.jl new file mode 100644 index 0000000000..4cdc444716 --- /dev/null +++ b/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 diff --git a/test/runtests.jl b/test/runtests.jl index 8c30bf30cb..fb9e43a22e 100644 --- a/test/runtests.jl +++ b/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") From f8ecf41fa460c6449523ed81c89c0dcaf71dcfa4 Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Wed, 6 Jul 2022 20:04:08 +1200 Subject: [PATCH 5/5] Add CHANGELOG --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index cd3746d92b..96fab76071 100644 --- a/CHANGELOG.md +++ b/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 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079