Skip to content

Commit fcee2bf

Browse files
vchuravyvchuravy
authored
Separate decision making repo from deploy repo (#2692)
1 parent ced42e5 commit fcee2bf

File tree

5 files changed

+106
-32
lines changed

5 files changed

+106
-32
lines changed

‎CHANGELOG.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1010
* Added anchor links to admonition blocks, making it possible to create direct links to specific admonitions. ([#2505], [#2676], [#2688])
1111
* Added different banners for dev and unreleased docs ([#2382], [#2682])
1212
* Added an API function `writer_supports_ansicolor` for a Documenter writer to indicate that it supports rendering ANSI-colored strings. This is useful for new backends that may be implemented. ([#2490])
13+
* Introduced the `deploy_repo` keyword argument for `deploydocs` to better support out-of-repo documentation deployments ([#2692])
1314

1415
### Fixed
1516

@@ -2035,6 +2036,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
20352036
[#2676]: https://github.com/JuliaDocs/Documenter.jl/issues/2676
20362037
[#2682]: https://github.com/JuliaDocs/Documenter.jl/issues/2682
20372038
[#2685]: https://github.com/JuliaDocs/Documenter.jl/issues/2685
2039+
[#2692]: https://github.com/JuliaDocs/Documenter.jl/pull/2692
20382040
[#2693]: https://github.com/JuliaDocs/Documenter.jl/issues/2693
20392041
[JuliaLang/julia#36953]: https://github.com/JuliaLang/julia/issues/36953
20402042
[JuliaLang/julia#38054]: https://github.com/JuliaLang/julia/issues/38054

‎docs/src/man/hosting.md

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -602,15 +602,10 @@ repository on a "target" repo:
602602
4. Adapt `docs/make.jl` to deploy on "target" repository:
603603

604604
```julia
605-
# url of target repo
606-
repo = "github.com/TargetRepoOrg/TargetRepo.git"
607-
608-
# You have to override the corresponding environment variable that
609-
# deplodocs uses to determine if it is deploying to the correct repository.
610-
# For GitHub, it's the GITHUB_REPOSITORY variable:
611-
withenv("GITHUB_REPOSITORY" => repo) do
612-
deploydocs(repo=repo)
613-
end
605+
deploydocs(
606+
repo="github.com/SourceRepoOrg/SourceRepo",
607+
deploy_repo="github.com/TargetRepoOrg/TargetRepo"
608+
)
614609
```
615610

616611
## Deploying from a monorepo

‎src/deployconfig.jl

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,8 @@ end
166166
function deploy_folder(
167167
cfg::Travis;
168168
repo,
169-
repo_previews = repo,
169+
repo_previews = nothing,
170+
deploy_repo = nothing,
170171
branch = "gh-pages",
171172
branch_previews = branch,
172173
devbranch,
@@ -201,7 +202,7 @@ function deploy_folder(
201202
all_ok &= tag_ok
202203
println(io, "- $(marker(tag_ok)) ENV[\"TRAVIS_TAG\"] contains a valid VersionNumber")
203204
deploy_branch = branch
204-
deploy_repo = repo
205+
deploy_repo = something(deploy_repo, repo)
205206
is_preview = false
206207
## Deploy to folder according to the tag
207208
subfolder = tag_nobuild
@@ -215,7 +216,7 @@ function deploy_folder(
215216
all_ok &= branch_ok
216217
println(io, "- $(marker(branch_ok)) ENV[\"TRAVIS_BRANCH\"] matches devbranch=\"$(devbranch)\"")
217218
deploy_branch = branch
218-
deploy_repo = repo
219+
deploy_repo = something(deploy_repo, repo)
219220
is_preview = false
220221
## Deploy to deploydocs devurl kwarg
221222
subfolder = devurl
@@ -228,7 +229,7 @@ function deploy_folder(
228229
all_ok &= btype_ok
229230
println(io, "- $(marker(btype_ok)) `push_preview` keyword argument to deploydocs is `true`")
230231
deploy_branch = branch_previews
231-
deploy_repo = repo_previews
232+
deploy_repo = something(repo_previews, deploy_repo, repo)
232233
is_preview = true
233234
## deploy to previews/PR
234235
subfolder = "previews/PR$(something(pr_number, 0))"
@@ -312,7 +313,8 @@ end
312313
function deploy_folder(
313314
cfg::GitHubActions;
314315
repo,
315-
repo_previews = repo,
316+
repo_previews = nothing,
317+
deploy_repo = nothing,
316318
branch = "gh-pages",
317319
branch_previews = branch,
318320
devbranch,
@@ -348,7 +350,7 @@ function deploy_folder(
348350
all_ok &= tag_ok
349351
println(io, "- $(marker(tag_ok)) ENV[\"GITHUB_REF\"]=\"$(cfg.github_ref)\" contains a valid VersionNumber")
350352
deploy_branch = branch
351-
deploy_repo = repo
353+
deploy_repo = something(deploy_repo, repo)
352354
is_preview = false
353355
## Deploy to folder according to the tag
354356
subfolder = m === nothing ? nothing : tag_nobuild
@@ -363,7 +365,7 @@ function deploy_folder(
363365
all_ok &= branch_ok
364366
println(io, "- $(marker(branch_ok)) ENV[\"GITHUB_REF\"] matches devbranch=\"$(devbranch)\"")
365367
deploy_branch = branch
366-
deploy_repo = repo
368+
deploy_repo = something(deploy_repo, repo)
367369
is_preview = false
368370
## Deploy to deploydocs devurl kwarg
369371
subfolder = devurl
@@ -382,7 +384,7 @@ function deploy_folder(
382384
all_ok &= btype_ok
383385
println(io, "- $(marker(btype_ok)) `push_preview` keyword argument to deploydocs is `true`")
384386
deploy_branch = branch_previews
385-
deploy_repo = repo_previews
387+
deploy_repo = something(repo_previews, deploy_repo, repo)
386388
is_preview = true
387389
## deploydocs to previews/PR
388390
subfolder = "previews/PR$(something(pr_number, 0))"
@@ -607,7 +609,8 @@ end
607609
function deploy_folder(
608610
cfg::GitLab;
609611
repo,
610-
repo_previews = repo,
612+
repo_previews = nothing,
613+
deploy_repo = nothing,
611614
devbranch,
612615
push_preview,
613616
devurl,
@@ -650,7 +653,7 @@ function deploy_folder(
650653
is_preview = false
651654
subfolder = tag_nobuild
652655
deploy_branch = branch
653-
deploy_repo = repo
656+
deploy_repo = something(deploy_repo, repo)
654657
elseif build_type == :preview
655658
pr_number = tryparse(Int, cfg.pull_request_iid)
656659
pr_ok = pr_number !== nothing
@@ -669,7 +672,7 @@ function deploy_folder(
669672
## deploy to previews/PR
670673
subfolder = "previews/PR$(something(pr_number, 0))"
671674
deploy_branch = branch_previews
672-
deploy_repo = repo_previews
675+
deploy_repo = something(repo_previews, deploy_repo, repo)
673676
else
674677
branch_ok = !isempty(cfg.commit_tag) || cfg.commit_branch == devbranch
675678
all_ok &= branch_ok
@@ -680,7 +683,7 @@ function deploy_folder(
680683
is_preview = false
681684
subfolder = devurl
682685
deploy_branch = branch
683-
deploy_repo = repo
686+
deploy_repo = something(deploy_repo, repo)
684687
end
685688

686689
key_ok = env_nonempty("DOCUMENTER_KEY")
@@ -750,7 +753,8 @@ end
750753
function deploy_folder(
751754
cfg::Buildkite;
752755
repo,
753-
repo_previews = repo,
756+
repo_previews = nothing,
757+
deploy_repo = nothing,
754758
devbranch,
755759
push_preview,
756760
devurl,
@@ -791,7 +795,7 @@ function deploy_folder(
791795
is_preview = false
792796
subfolder = tag_nobuild
793797
deploy_branch = branch
794-
deploy_repo = repo
798+
deploy_repo = something(deploy_repo, repo)
795799
elseif build_type == :preview
796800
pr_number = tryparse(Int, cfg.pull_request)
797801
pr_ok = pr_number !== nothing
@@ -810,7 +814,7 @@ function deploy_folder(
810814
## deploy to previews/PR
811815
subfolder = "previews/PR$(something(pr_number, 0))"
812816
deploy_branch = branch_previews
813-
deploy_repo = repo_previews
817+
deploy_repo = something(repo_previews, deploy_repo, repo)
814818
else
815819
branch_ok = !isempty(cfg.commit_tag) || cfg.commit_branch == devbranch
816820
all_ok &= branch_ok
@@ -821,7 +825,7 @@ function deploy_folder(
821825
is_preview = false
822826
subfolder = devurl
823827
deploy_branch = branch
824-
deploy_repo = repo
828+
deploy_repo = something(deploy_repo, repo)
825829
end
826830

827831
key_ok = env_nonempty("DOCUMENTER_KEY")
@@ -1003,7 +1007,8 @@ end
10031007
function deploy_folder(
10041008
cfg::Woodpecker;
10051009
repo,
1006-
repo_previews = repo,
1010+
repo_previews = nothing,
1011+
deploy_repo = nothing,
10071012
branch = "pages",
10081013
branch_previews = branch,
10091014
devbranch,
@@ -1047,7 +1052,7 @@ function deploy_folder(
10471052
all_ok &= tag_ok
10481053
println(io, "- $(marker(tag_ok)) ENV[\"CI_COMMIT_TAG\"]=\"$(cfg.woodpecker_tag)\" contains a valid VersionNumber")
10491054
deploy_branch = branch
1050-
deploy_repo = repo
1055+
deploy_repo = something(deploy_repo, repo)
10511056
is_preview = false
10521057
## Deploy to folder according to the tag
10531058
subfolder = tag_nobuild
@@ -1062,7 +1067,7 @@ function deploy_folder(
10621067
all_ok &= branch_ok
10631068
println(io, "- $(marker(branch_ok)) ENV[\"CI_COMMIT_REF\"] matches devbranch=\"$(devbranch)\"")
10641069
deploy_branch = branch
1065-
deploy_repo = repo
1070+
deploy_repo = something(deploy_repo, repo)
10661071
is_preview = false
10671072
## Deploy to deploydocs devurl kwarg
10681073
subfolder = devurl
@@ -1081,7 +1086,7 @@ function deploy_folder(
10811086
all_ok &= btype_ok
10821087
println(io, "- $(marker(btype_ok)) `push_preview` keyword argument to deploydocs is `true`")
10831088
deploy_branch = branch_previews
1084-
deploy_repo = repo_previews
1089+
deploy_repo = something(repo_previews, deploy_repo, repo)
10851090
is_preview = true
10861091
## deploydocs to previews/PR
10871092
subfolder = "previews/PR$(something(pr_number1, 0))"

‎src/deploydocs.jl

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@
1616
forcepush = false,
1717
deploy_config = auto_detect_deploy_system(),
1818
push_preview = false,
19-
repo_previews = repo,
19+
repo_previews = nothing,
20+
deploy_repo = nothing,
2021
branch_previews = branch,
2122
tag_prefix = "",
2223
)
@@ -128,6 +129,12 @@ If `versions = nothing` documentation will be deployed directly to the "root", i
128129
not to a versioned subfolder. See the manual section on
129130
[Deploying without the versioning scheme](@ref) for more details.
130131
132+
**`deploy_repo`** can be used to override the remote repository to deploy to, which
133+
normally will be the same as `repo` (if this is unset or set to `nothing`). This is mostly
134+
used when the documentation is deployed to a dedicated "docs hosting repository", usually
135+
to avoid issues with the main repository's `gh-pages` branch getting too large. The
136+
expected format of the argument is the same as for `repo`.
137+
131138
**`push_preview`** a boolean that specifies if preview documentation should be
132139
deployed from pull requests or not. If your published documentation is hosted
133140
at `"https://USER.github.io/PACKAGE.jl/stable`, by default the preview will be
@@ -139,7 +146,8 @@ forks.
139146
It defaults to the value of `branch`.
140147
141148
**`repo_previews`** is the remote repository to which pull request previews are
142-
deployed. It defaults to the value of `repo`.
149+
deployed. It defaults to the value of `repo`, and when specified manually, must
150+
follow its formatting scheme.
143151
144152
!!! note
145153
Pull requests made from forks will not have previews.
@@ -190,8 +198,9 @@ function deploydocs(;
190198

191199
repo = error("no 'repo' keyword provided."),
192200
branch = "gh-pages",
201+
deploy_repo = nothing,
193202

194-
repo_previews = repo,
203+
repo_previews = nothing,
195204
branch_previews = branch,
196205

197206
deps = nothing,
@@ -230,6 +239,7 @@ function deploydocs(;
230239
push_preview = push_preview,
231240
repo = repo,
232241
repo_previews = repo_previews,
242+
deploy_repo = deploy_repo,
233243
tag_prefix
234244
)
235245
if deploy_decision.all_ok

‎test/deployconfig.jl

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,28 @@ end
180180
@test Documenter.authentication_method(cfg) === Documenter.SSH
181181
@test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
182182
end
183+
# External Repo: Regular tag build with SSH deploy key (SSH key prioritized)
184+
withenv(
185+
"GITHUB_EVENT_NAME" => "push",
186+
"GITHUB_REPOSITORY" => "JuliaDocs/Documenter.jl",
187+
"GITHUB_REF" => "refs/tags/v1.2.3",
188+
"GITHUB_ACTOR" => "github-actions",
189+
"GITHUB_TOKEN" => "SGVsbG8sIHdvcmxkLg==",
190+
"DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
191+
) do
192+
cfg = Documenter.GitHubActions()
193+
d = Documenter.deploy_folder(
194+
cfg; repo = "github.com/JuliaDocs/Documenter.jl.git",
195+
deploy_repo = "github.com/JuliaDocs/DocumenterDocs.jl.git",
196+
devbranch = "master", devurl = "dev", push_preview = true
197+
)
198+
@test d.all_ok
199+
@test d.subfolder == "v1.2.3"
200+
@test d.repo == "github.com/JuliaDocs/DocumenterDocs.jl.git"
201+
@test d.branch == "gh-pages"
202+
@test Documenter.authentication_method(cfg) === Documenter.SSH
203+
@test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
204+
end
183205
# Regular tag build with GITHUB_TOKEN and with tag prefix
184206
withenv(
185207
"GITHUB_EVENT_NAME" => "push",
@@ -395,6 +417,46 @@ end
395417
@test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
396418
@test Documenter.documenter_key_previews(cfg) === "SGVsbG8sIHdvcmxkLw=="
397419
end
420+
# External Repo: Regular pull request build with GITHUB_TOKEN
421+
withenv(
422+
"GITHUB_EVENT_NAME" => "pull_request",
423+
"GITHUB_REPOSITORY" => "JuliaDocs/Documenter.jl",
424+
"GITHUB_REF" => "refs/pull/1962/merge",
425+
"GITHUB_ACTOR" => "github-actions",
426+
"DOCUMENTER_KEY" => nothing,
427+
) do
428+
cfg = Documenter.GitHubActions()
429+
d = Documenter.deploy_folder(
430+
cfg; repo = "github.com/JuliaDocs/Documenter.jl.git",
431+
deploy_repo = "github.com/JuliaDocs/DocumenterDocs.jl.git",
432+
devbranch = "master", devurl = "hello-world", push_preview = true
433+
)
434+
@test d.all_ok
435+
@test d.subfolder == "previews/PR1962"
436+
@test d.repo == "github.com/JuliaDocs/DocumenterDocs.jl.git"
437+
@test d.branch == "gh-pages"
438+
end
439+
# External Repo: Regular pull request build with SSH deploy key (SSH key prioritized), but push previews to a different repo and different branch
440+
withenv(
441+
"GITHUB_EVENT_NAME" => "pull_request",
442+
"GITHUB_REPOSITORY" => "JuliaDocs/Documenter.jl",
443+
"GITHUB_REF" => "refs/pull/1962/merge",
444+
"GITHUB_ACTOR" => "github-actions",
445+
"DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
446+
) do
447+
cfg = Documenter.GitHubActions()
448+
d = Documenter.deploy_folder(
449+
cfg; repo = "github.com/JuliaDocs/Documenter.jl.git",
450+
devbranch = "master", devurl = "hello-world", push_preview = true,
451+
repo_previews = "github.com/JuliaDocs/Documenter-previews.jl.git",
452+
deploy_repo = "github.com/JuliaDocs/DocumenterDocs.jl.git",
453+
branch_previews = "gh-pages-previews"
454+
)
455+
@test d.all_ok
456+
@test d.subfolder == "previews/PR1962"
457+
@test d.repo == "github.com/JuliaDocs/Documenter-previews.jl.git" # prioritize repo_previews
458+
@test d.branch == "gh-pages-previews"
459+
end
398460
end
399461
# Missing environment variables
400462
withenv(

0 commit comments

Comments
 (0)