Skip to content

Commit 8eb8f72

Browse files
klamikeklamike
committed
allow external previews
1 parent 74107d9 commit 8eb8f72

File tree

2 files changed

+147
-0
lines changed

2 files changed

+147
-0
lines changed

‎docs/make.jl‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,9 @@ end
5656
# Documenter can also automatically deploy documentation to gh-pages.
5757
# See "Hosting Documentation" and deploydocs() in the Documenter manual
5858
# for more information.
59+
include("patch.jl")
5960
deploydocs(
6061
repo="github.com/LearningToOptimize/LearningToControlClass.git",
6162
push_preview=true,
63+
deploy_config=L2CCGitHubActionsAllowExternalPreviews()
6264
)

‎docs/patch.jl‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
struct L2CCGitHubActionsAllowExternalPreviews <: Documenter.GithubActions
2+
github_repository::String
3+
github_event_name::String
4+
github_ref::String
5+
github_triggering_actor::String
6+
end
7+
function L2CCGitHubActionsAllowExternalPreviews()
8+
github_repository = get(ENV, "GITHUB_REPOSITORY", "") # "JuliaDocs/Documenter.jl"
9+
github_event_name = get(ENV, "GITHUB_EVENT_NAME", "") # "push", "pull_request" or "cron" (?)
10+
github_ref = get(ENV, "GITHUB_REF", "") # "refs/heads/$(branchname)" for branch, "refs/tags/$(tagname)" for tags
11+
github_triggering_actor = get(ENV, "GITHUB_TRIGGERING_ACTOR", "")
12+
return L2CCGitHubActionsAllowExternalPreviews(github_repository, github_event_name, github_ref,
13+
github_triggering_actor)
14+
end
15+
16+
function Documenter.deploy_folder(
17+
cfg::L2CCGitHubActionsAllowExternalPreviews;
18+
repo,
19+
repo_previews = nothing,
20+
deploy_repo = nothing,
21+
branch = "gh-pages",
22+
branch_previews = branch,
23+
devbranch,
24+
push_preview,
25+
devurl,
26+
tag_prefix = "",
27+
kwargs...
28+
)
29+
io = IOBuffer()
30+
all_ok = true
31+
## Determine build type
32+
if cfg.github_event_name == "pull_request"
33+
build_type = :preview
34+
elseif occursin(r"^refs\/tags\/(.*)$", cfg.github_ref)
35+
build_type = :release
36+
else
37+
build_type = :devbranch
38+
end
39+
println(io, "Deployment criteria for deploying $(build_type) build from GitHub Actions:")
40+
## The deploydocs' repo should match GITHUB_REPOSITORY
41+
repo_ok = occursin(cfg.github_repository, repo)
42+
all_ok &= repo_ok
43+
println(io, "- $(marker(repo_ok)) ENV[\"GITHUB_REPOSITORY\"]=\"$(cfg.github_repository)\" occurs in repo=\"$(repo)\"")
44+
if build_type === :release
45+
## Do not deploy for PRs
46+
event_ok = in(cfg.github_event_name, ["push", "workflow_dispatch", "schedule", "release"])
47+
all_ok &= event_ok
48+
println(io, "- $(marker(event_ok)) ENV[\"GITHUB_EVENT_NAME\"]=\"$(cfg.github_event_name)\" is \"push\", \"workflow_dispatch\", \"schedule\" or \"release\"")
49+
## If a tag exist it should be a valid VersionNumber
50+
m = match(r"^refs\/tags\/(.*)$", cfg.github_ref)
51+
tag_nobuild = version_tag_strip_build(m.captures[1]; tag_prefix)
52+
tag_ok = tag_nobuild !== nothing
53+
all_ok &= tag_ok
54+
println(io, "- $(marker(tag_ok)) ENV[\"GITHUB_REF\"]=\"$(cfg.github_ref)\" contains a valid VersionNumber")
55+
deploy_branch = branch
56+
deploy_repo = something(deploy_repo, repo)
57+
is_preview = false
58+
## Deploy to folder according to the tag
59+
subfolder = m === nothing ? nothing : tag_nobuild
60+
elseif build_type === :devbranch
61+
## Do not deploy for PRs
62+
event_ok = in(cfg.github_event_name, ["push", "workflow_dispatch", "schedule"])
63+
all_ok &= event_ok
64+
println(io, "- $(marker(event_ok)) ENV[\"GITHUB_EVENT_NAME\"]=\"$(cfg.github_event_name)\" is \"push\", \"workflow_dispatch\" or \"schedule\"")
65+
## deploydocs' devbranch should match the current branch
66+
m = match(r"^refs\/heads\/(.*)$", cfg.github_ref)
67+
branch_ok = m === nothing ? false : String(m.captures[1]) == devbranch
68+
all_ok &= branch_ok
69+
println(io, "- $(marker(branch_ok)) ENV[\"GITHUB_REF\"] matches devbranch=\"$(devbranch)\"")
70+
deploy_branch = branch
71+
deploy_repo = something(deploy_repo, repo)
72+
is_preview = false
73+
## Deploy to deploydocs devurl kwarg
74+
subfolder = devurl
75+
else # build_type === :preview
76+
m = match(r"refs\/pull\/(\d+)\/merge", cfg.github_ref)
77+
pr_number = tryparse(Int, m === nothing ? "" : m.captures[1])
78+
pr_ok = pr_number !== nothing
79+
all_ok &= pr_ok
80+
println(io, "- $(marker(pr_ok)) ENV[\"GITHUB_REF\"] corresponds to a PR number")
81+
################################################################################
82+
## Begin edits for L2CC
83+
##
84+
## Remove the PR origin checking:
85+
##
86+
# if pr_ok
87+
# pr_origin_matches_repo = verify_github_pull_repository(cfg.github_repository, pr_number)
88+
# all_ok &= pr_origin_matches_repo
89+
# println(io, "- $(marker(pr_origin_matches_repo)) PR originates from the same repository")
90+
# end
91+
##
92+
## End edits for L2CC
93+
################################################################################
94+
btype_ok = push_preview
95+
all_ok &= btype_ok
96+
println(io, "- $(marker(btype_ok)) `push_preview` keyword argument to deploydocs is `true`")
97+
deploy_branch = branch_previews
98+
deploy_repo = something(repo_previews, deploy_repo, repo)
99+
is_preview = true
100+
## deploydocs to previews/PR
101+
subfolder = "previews/PR$(something(pr_number, 0))"
102+
end
103+
## GITHUB_ACTOR should exist (just check here and extract the value later)
104+
actor_ok = env_nonempty("GITHUB_ACTOR")
105+
all_ok &= actor_ok
106+
println(io, "- $(marker(actor_ok)) ENV[\"GITHUB_ACTOR\"] exists and is non-empty")
107+
## GITHUB_TOKEN or DOCUMENTER_KEY should exist (just check here and extract the value later)
108+
token_ok = env_nonempty("GITHUB_TOKEN")
109+
key_ok = env_nonempty("DOCUMENTER_KEY")
110+
auth_ok = token_ok | key_ok
111+
all_ok &= auth_ok
112+
if key_ok
113+
println(io, "- $(marker(key_ok)) ENV[\"DOCUMENTER_KEY\"] exists and is non-empty")
114+
elseif token_ok
115+
println(io, "- $(marker(token_ok)) ENV[\"GITHUB_TOKEN\"] exists and is non-empty")
116+
else
117+
println(io, "- $(marker(auth_ok)) ENV[\"DOCUMENTER_KEY\"] or ENV[\"GITHUB_TOKEN\"] exists and is non-empty")
118+
end
119+
print(io, "Deploying: $(marker(all_ok))")
120+
@info String(take!(io))
121+
if build_type === :devbranch && !branch_ok && devbranch == "master" && cfg.github_ref == "refs/heads/main"
122+
@warn """
123+
Possible deploydocs() misconfiguration: main vs master
124+
Documenter's configured primary development branch (`devbranch`) is "master", but the
125+
current branch (from \$GITHUB_REF) is "main". This can happen because Documenter uses
126+
GitHub's old default primary branch name as the default value for `devbranch`.
127+
128+
If your primary development branch is 'main', you must explicitly pass `devbranch = "main"`
129+
to deploydocs.
130+
131+
See #1443 for more discussion: https://github.com/JuliaDocs/Documenter.jl/issues/1443
132+
"""
133+
end
134+
if all_ok
135+
return DeployDecision(;
136+
all_ok = true,
137+
branch = deploy_branch,
138+
is_preview = is_preview,
139+
repo = deploy_repo,
140+
subfolder = subfolder
141+
)
142+
else
143+
return DeployDecision(; all_ok = false)
144+
end
145+
end

0 commit comments

Comments
 (0)