From 42af534003fcc85df5ad27b1ae1d13aa8bb780bd Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Tue, 1 Jan 2019 05:39:16 +0530 Subject: [PATCH 01/25] First pass at decoupling manual deploy from generic CI --- src/Documenter.jl | 39 +++++++++++++-------------------------- 1 file changed, 13 insertions(+), 26 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index a06e5287a2..1b4b115d1e 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -608,12 +608,6 @@ the generated html. The following entries are valied in the `versions` vector: Travis ([`TRAVIS`](@ref)). Other options are [`GITLAB_CI`](@ref), [`CIRRUS_CI`](@ref), [`DRONE`](@ref), and [`APPVEYOR`](@ref). -**tag** provides a specific tag, if you want one to be set. Providing an empty string (if -building manually) will make the documentation build as if there was no tag; but, if run on -CI, it will read the appropriate environment variable to determine if a tag exists or not; -if there is a provided tag, then that will take precedence over the environment variable, -which will take precedence over the empty string. - # Environment variables - **`DOCUMENTER_KEY`**: must contain the Base64-encoded SSH private key for the repository. @@ -677,8 +671,7 @@ function deploydocs(; devurl = "dev", versions = ["stable" => "v^", "v#.#", devurl => devurl], forcepush::Bool = false, - uploader::CI_SYSTEM = TRAVIS, - tag = "" + uploader::CI_SYSTEM = TRAVIS ) # deprecation of latest kwarg (renamed to devbranch) if latest !== nothing @@ -702,21 +695,21 @@ function deploydocs(; return end - local cibranch, pull_request, repo_slug, localtag, event_type, finaldeploy + local cibranch, pull_request, repo_slug, tag, event_type, finaldeploy if haskey(ENV, "CI") - cibranch, pull_request, repo_slug, citag, event_type, finaldeploy = read_ci_env(true, uploader=uploader) - localtag = isempty(tag) ? citag : tag + cibranch, pull_request, repo_slug, tag, event_type, finaldeploy = read_ci_env(true, uploader=uploader) else - cibranch = devbranch - pull_request = false - repo_slug = repo - localtag = isempty(tag) ? read_ci_env()[:tag] : tag - event_type = "manual" - finaldeploy = haskey(ENV, "DOCUMENTER_KEY") + # TODO add a better way to manually deploy + @error """ + You seem to be deploying manually, but ENV[\"CI\"] is not set. + Please set the appropriate environment variables before you try to deploy. + These environment variables can be seen in the documentation for `deploydocs`, + which can be accessed by `?deploydocs` in the REPL. + """ end - # Get environment variables. + # Get authentication key. documenter_key = get(ENV, "DOCUMENTER_KEY", "") @@ -743,7 +736,7 @@ function deploydocs(; ## Do not deploy for PRs pr_ok = pull_request in ("false", "False") # Appveyor env vars are capitalized on Windows ## If a tag exists, it should be a valid VersionNumber - tag_ok = isempty(localtag) || occursin(Base.VERSION_REGEX, tag) + tag_ok = isempty(tag) || occursin(Base.VERSION_REGEX, tag) ## If no tag exists deploydocs' devbranch should match the CI branch branch_ok = !isempty(tag) || cibranch == devbranch ## DOCUMENTER_KEY should exist @@ -767,13 +760,7 @@ function deploydocs(; - $(marker(finaldeploy)) CI service is $uploader Deploying: $(marker(should_deploy)) """ - else - @info """ - Deploying manually. - Deployment criteria: - - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists - Deploying: $(marker(should_deploy)) - """ + # TODO add a better way to manually deploy end if should_deploy From 1cb28eb7a3ed37a7a382213c7792a68f6927032a Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sat, 13 Jul 2019 14:48:43 +0530 Subject: [PATCH 02/25] Check env vars for non-Travis CI platforms Special cases are now Travis, Gitlab, Drone, Cirrus and Appveyor. Not all of these CI services provide the same information as Travis does, or in the same way, so some massaging of variable contents is required. Appveyor is arguably one of the worse ones here. This is untested on most of these CI systems at the time this was committed; hence, any feedback is appreciated. --- src/Documenter.jl | 106 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 86 insertions(+), 20 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index d347378283..71b9feffa9 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -547,13 +547,78 @@ function deploydocs(; return end + if haskey(ENV, "CI") + + if haskey(ENV, "TRAVIS") + + @info "Travis CI detected" + + branch = get(ENV, "TRAVIS_BRANCH", "") + pull_request = get(ENV, "TRAVIS_PULL_REQUEST", "") + repo_slug = get(ENV, "TRAVIS_REPO_SLUG", "") + tag = get(ENV, "TRAVIS_TAG", "") + event_type = get(ENV, "TRAVIS_EVENT_TYPE", "") + + elseif haskey(ENV, "GITLAB_CI") + + @info "Gitlab CI detected" + + branch = get(ENV, "CI_COMMIT_REF_NAME", "") + pull_request = get(ENV, "CI_MERGE_REQUEST_ID", "false") + repo_slug = get(ENV, "CI_PROJECT_PATH", "") + tag = get(ENV, "CI_COMMIT_TAG", "") + event_type = get(ENV, "CI_PIPELINE_SOURCE", "") + + elseif haskey(ENV, "DRONE") + + @info "Drone CI detected" + + branch = get(ENV, "DRONE_COMMIT_BRANCH", "") + pull_request = get(ENV, "DRONE_PULL_REQUEST", "false") + repo_slug = get(ENV, "DRONE_REPO_NAMESPACE", "") * "/" * get(ENV, "DRONE_REPO_NAME", "") + tag = get(ENV, "DRONE_TAG", "") + event_type = get(ENV, "DRONE_BUILD_EVENT", "") + + elseif haskey(ENV, "CIRRUS_CI") + + @info "Cirrus CI detected" + + branch = get(ENV, "CIRRUS_BRANCH", "") + pull_request = get(ENV, "CIRRUS_PR", "false") + repo_slug = get(ENV, "CIRRUS_REPO_FULL_NAME", "") + tag = get(ENV, "CIRRUS_TAG", "") + event_type = "unknown" # Cirrus CI doesn't seem to provide the triggering event... + + elseif haskey(ENV, "APPVEYOR") # the worst of them all + + @info "AppVeyor CI detected" + + pull_request = get(ENV, "APPVEYOR_PULL_REQUEST_NUMBER", "false") + branch = if haskey(ENV, "APPVEYOR_PULL_REQUEST_NUMBER" ) + ENV["APPVEYOR_PULL_REQUEST_HEAD_REPO_BRANCH"] + else + get(ENV, "APPVEYOR_REPO_BRANCH", "") + end + repo_slug = get(ENV, "APPVEYOR_PROJECT_SLUG", "") + tag = get(ENV, "APPVEYOR_REPO_TAG_NAME", "") + event_type = "unknown" # Appveyor has four env vars for this... + + else + + error( + """ + We don't recognize the CI service you're running, or haven't added support for it. + We currently support Travis-CI, Gitlab CI, Drone CI, Cirrus CI and AppVeyor. + """ + ) + + end + + end + # Get environment variables. - documenter_key = get(ENV, "DOCUMENTER_KEY", "") - travis_branch = get(ENV, "TRAVIS_BRANCH", "") - travis_pull_request = get(ENV, "TRAVIS_PULL_REQUEST", "") - travis_repo_slug = get(ENV, "TRAVIS_REPO_SLUG", "") - travis_tag = get(ENV, "TRAVIS_TAG", "") - travis_event_type = get(ENV, "TRAVIS_EVENT_TYPE", "") + documenter_key = get(ENV, "DOCUMENTER_KEY", "") + # Other variables. @@ -573,28 +638,29 @@ function deploydocs(; end # Check criteria for deployment - ## The deploydocs' repo should match TRAVIS_REPO_SLUG - repo_ok = occursin(travis_repo_slug, repo) + ## The deploydocs' repo should match the repo slug provided by CI + repo_ok = occursin(repo_slug, repo) ## Do not deploy for PRs - pr_ok = travis_pull_request == "false" - ## If a tag exist it should be a valid VersionNumber - tag_ok = isempty(travis_tag) || occursin(Base.VERSION_REGEX, travis_tag) - ## If no tag exists deploydocs' devbranch should match TRAVIS_BRANCH - branch_ok = !isempty(travis_tag) || travis_branch == devbranch + pr_ok = pull_request in ("false", "False") # Appveyor env vars are capitalized on Windows + ## If a tag exists, it should be a valid VersionNumber + tag_ok = isempty(tag) || occursin(Base.VERSION_REGEX, tag) + ## If no tag exists deploydocs' devbranch should match the CI branch + branch_ok = !isempty(tag) || branch == devbranch ## DOCUMENTER_KEY should exist key_ok = !isempty(documenter_key) ## Cron jobs should not deploy - type_ok = travis_event_type != "cron" + type_ok = event_type != "cron" + should_deploy = repo_ok && pr_ok && tag_ok && branch_ok && key_ok && type_ok marker(x) = x ? "✔" : "✘" @info """Deployment criteria: - - $(marker(repo_ok)) ENV["TRAVIS_REPO_SLUG"]="$(travis_repo_slug)" occurs in repo="$(repo)" - - $(marker(pr_ok)) ENV["TRAVIS_PULL_REQUEST"]="$(travis_pull_request)" is "false" - - $(marker(tag_ok)) ENV["TRAVIS_TAG"]="$(travis_tag)" is (i) empty or (ii) a valid VersionNumber - - $(marker(branch_ok)) ENV["TRAVIS_BRANCH"]="$(travis_branch)" matches devbranch="$(devbranch)" (if tag is empty) + - $(marker(repo_ok)) CI repo slug = "$(repo_slug)" occurs in repo = "$(repo)" + - $(marker(pr_ok)) CI pull request indicator = "$(pull_request)" is "false" + - $(marker(tag_ok)) CI tag indicator = "$(tag)" is (i) empty or (ii) a valid VersionNumber + - $(marker(branch_ok)) CI branch = "$(branch)" matches devbranch="$(devbranch)" (if tag is empty) - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists - - $(marker(type_ok)) ENV["TRAVIS_EVENT_TYPE"]="$(travis_event_type)" is not "cron" + - $(marker(type_ok)) CI event type = "$(event_type)" is not "cron" Deploying: $(marker(should_deploy)) """ @@ -620,7 +686,7 @@ function deploydocs(; git_push( root, temp, repo; branch=branch, dirname=dirname, target=target, - tag=travis_tag, key=documenter_key, sha=sha, + tag=tag, key=documenter_key, sha=sha, devurl = devurl, versions = versions, forcepush = forcepush, ) end From 74679200664833b972af1298931504de731d2340 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sat, 13 Jul 2019 16:19:19 +0530 Subject: [PATCH 03/25] implement preferred uploader --- src/Documenter.jl | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index 71b9feffa9..fc680479fb 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -462,12 +462,16 @@ the generated html. The following entries are valied in the `versions` vector: The second argument can be `"v^"`, to point to the maximum version docs (as in e.g. `"stable" => "v^"`). +**uploader** determines _which_ CI service will upload the documentation. Defaults to Travis +(`"TRAVIS"`). Other options are `"GITLAB_CI"`, `"CIRRUS_CI"`, `"DRONE"`, and `"APPVEYOR"`. + # Environment variables -[`deploydocs`](@ref)'s behavior is influenced by the following environment variables, many -of which are specific to the [Travis CI platform](https://travis-ci.com/). +- **`DOCUMENTER_KEY`**: must contain the Base64-encoded SSH private key for the repository. - - **`DOCUMENTER_KEY`**: must contain the Base64-encoded SSH private key for the repository. +[`deploydocs`](@ref)'s behavior is influenced by environment variables when in a CI environment. +Please refer to the source to see what these variables are for each system; below is the description +of the Travis CI environment variables that [`deploydocs`](@ref) parses. - **`TRAVIS_PULL_REQUEST`**: must be set to `false`. @@ -495,7 +499,7 @@ of which are specific to the [Travis CI platform](https://travis-ci.com/). version number in `TRAVIS_TAG` instead. The `TRAVIS_*` variables are set automatically on Travis, but could be set manually to -appropriate values as well to run [`deploydocs`](@ref) locally or on other CI platforms. +appropriate values as well to run [`deploydocs`](@ref) locally. More information on how Travis sets the `TRAVIS_*` variables can be found in the [Travis documentation](https://docs.travis-ci.com/user/environment-variables/#default-environment-variables). @@ -524,6 +528,7 @@ function deploydocs(; devurl = "dev", versions = ["stable" => "v^", "v#.#", devurl => devurl], forcepush::Bool = false, + uploader = "TRAVIS" ) # deprecation of latest kwarg (renamed to devbranch) if latest !== nothing @@ -547,6 +552,8 @@ function deploydocs(; return end + local finaldeploy + if haskey(ENV, "CI") if haskey(ENV, "TRAVIS") @@ -559,6 +566,8 @@ function deploydocs(; tag = get(ENV, "TRAVIS_TAG", "") event_type = get(ENV, "TRAVIS_EVENT_TYPE", "") + finaldeploy = uploader == "TRAVIS" + elseif haskey(ENV, "GITLAB_CI") @info "Gitlab CI detected" @@ -569,6 +578,8 @@ function deploydocs(; tag = get(ENV, "CI_COMMIT_TAG", "") event_type = get(ENV, "CI_PIPELINE_SOURCE", "") + finaldeploy = uploader == "GITLAB_CI" + elseif haskey(ENV, "DRONE") @info "Drone CI detected" @@ -579,6 +590,8 @@ function deploydocs(; tag = get(ENV, "DRONE_TAG", "") event_type = get(ENV, "DRONE_BUILD_EVENT", "") + finaldeploy = uploader == "DRONE" + elseif haskey(ENV, "CIRRUS_CI") @info "Cirrus CI detected" @@ -589,6 +602,8 @@ function deploydocs(; tag = get(ENV, "CIRRUS_TAG", "") event_type = "unknown" # Cirrus CI doesn't seem to provide the triggering event... + finaldeploy = uploader == "CIRRUS_CI" + elseif haskey(ENV, "APPVEYOR") # the worst of them all @info "AppVeyor CI detected" @@ -603,6 +618,8 @@ function deploydocs(; tag = get(ENV, "APPVEYOR_REPO_TAG_NAME", "") event_type = "unknown" # Appveyor has four env vars for this... + finaldeploy = uploader == "APPVEYOR" + else error( @@ -651,7 +668,7 @@ function deploydocs(; ## Cron jobs should not deploy type_ok = event_type != "cron" - should_deploy = repo_ok && pr_ok && tag_ok && branch_ok && key_ok && type_ok + should_deploy = repo_ok && pr_ok && tag_ok && branch_ok && key_ok && type_ok && finaldeploy marker(x) = x ? "✔" : "✘" @info """Deployment criteria: @@ -661,6 +678,7 @@ function deploydocs(; - $(marker(branch_ok)) CI branch = "$(branch)" matches devbranch="$(devbranch)" (if tag is empty) - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists - $(marker(type_ok)) CI event type = "$(event_type)" is not "cron" + - $(marker(finaldeploy)) CI service is $uploader Deploying: $(marker(should_deploy)) """ From 2986dabaf91b11c789b165e4d4493020217f6d98 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 14 Jul 2019 06:41:24 +0530 Subject: [PATCH 04/25] Better pull request check message Co-Authored-By: Morten Piibeleht --- src/Documenter.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index fc680479fb..bbaaa2d883 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -673,7 +673,7 @@ function deploydocs(; marker(x) = x ? "✔" : "✘" @info """Deployment criteria: - $(marker(repo_ok)) CI repo slug = "$(repo_slug)" occurs in repo = "$(repo)" - - $(marker(pr_ok)) CI pull request indicator = "$(pull_request)" is "false" + - $(marker(pr_ok)) CI pull request indicator = "$(pull_request)" is "false" or "False" - $(marker(tag_ok)) CI tag indicator = "$(tag)" is (i) empty or (ii) a valid VersionNumber - $(marker(branch_ok)) CI branch = "$(branch)" matches devbranch="$(devbranch)" (if tag is empty) - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists From b970a9969b3f4516fb9c8fa5998c672a2db36203 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 14 Jul 2019 07:18:36 +0530 Subject: [PATCH 05/25] Make LaTeXWriter check for tag on all CIs --- src/Writers/LaTeXWriter.jl | 46 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/src/Writers/LaTeXWriter.jl b/src/Writers/LaTeXWriter.jl index a7041d192c..6d7539b2a7 100644 --- a/src/Writers/LaTeXWriter.jl +++ b/src/Writers/LaTeXWriter.jl @@ -90,7 +90,27 @@ function render(doc::Documents.Document, settings::LaTeX=LaTeX()) cp(joinpath(doc.user.root, doc.user.build), joinpath(path, "build")) cd(joinpath(path, "build")) do name = doc.user.sitename - let tag = get(ENV, "TRAVIS_TAG", "") + let tag = if haskey(ENV, "CI") + if haskey(ENV, "TRAVIS") + @info "Travis CI detected" + get(ENV, "TRAVIS_TAG", "") + elseif haskey(ENV, "GITLAB_CI") + @info "Gitlab CI detected" + get(ENV, "CI_COMMIT_TAG", "") + elseif haskey(ENV, "DRONE") + @info "Drone CI detected" + get(ENV, "DRONE_TAG", "") + elseif haskey(ENV, "CIRRUS_CI") + @info "Cirrus CI detected" + get(ENV, "CIRRUS_TAG", "") + elseif haskey(ENV, "APPVEYOR") + @info "AppVeyor CI detected" + get(ENV, "APPVEYOR_REPO_TAG_NAME", "") + end + else + "" + end + if occursin(Base.VERSION_REGEX, tag) v = VersionNumber(tag) name *= "-$(v.major).$(v.minor).$(v.patch)" @@ -181,6 +201,28 @@ end function writeheader(io::IO, doc::Documents.Document) custom = joinpath(doc.user.root, doc.user.source, "assets", "custom.sty") isfile(custom) ? cp(custom, "custom.sty"; force = true) : touch("custom.sty") + + tag = if haskey(ENV, "CI") + if haskey(ENV, "TRAVIS") + @info "Travis CI detected" + get(ENV, "TRAVIS_TAG", "") + elseif haskey(ENV, "GITLAB_CI") + @info "Gitlab CI detected" + get(ENV, "CI_COMMIT_TAG", "") + elseif haskey(ENV, "DRONE") + @info "Drone CI detected" + get(ENV, "DRONE_TAG", "") + elseif haskey(ENV, "CIRRUS_CI") + @info "Cirrus CI detected" + get(ENV, "CIRRUS_TAG", "") + elseif haskey(ENV, "APPVEYOR") + @info "AppVeyor CI detected" + get(ENV, "APPVEYOR_REPO_TAG_NAME", "") + end + @info "No tag detected..." + else + "" + end preamble = """ \\documentclass{memoir} @@ -190,7 +232,7 @@ function writeheader(io::IO, doc::Documents.Document) \\title{ {\\HUGE $(doc.user.sitename)}\\\\ - {\\Large $(get(ENV, "TRAVIS_TAG", ""))} + {\\Large $tag} } \\author{$(doc.user.authors)} From e48fafa4871c9375878d667590cf48bbf5942a74 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 14 Jul 2019 07:18:57 +0530 Subject: [PATCH 06/25] Create and export a CI_SYSTEM enum --- src/Documenter.jl | 51 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 11 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index bbaaa2d883..454dd4b227 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -57,6 +57,8 @@ import .Writers.HTMLWriter: HTML # --------------- export Deps, makedocs, deploydocs, hide, doctest, DocMeta +export TRAVIS, GITLAB_CI, CIRRUS_CI, DRONE, APPVEYOR + """ makedocs( root = "", @@ -371,6 +373,32 @@ makedocs( hide(root::Pair, children) = (true, root.first, root.second, map(hide, children)) hide(root::AbstractString, children) = (true, nothing, root, map(hide, children)) +""" + enum CI_SYSTEM + +The supported CI systems to deploy docs from, using Documenter.jl. + +Values: +* `TRAVIS` +* `GITLAB_CI` +* `CIRRUS_CI` +* `DRONE` +* `APPVEYOR` +""" +@enum CI_SYSTEM begin + + TRAVIS + + GITLAB_CI + + CIRRUS_CI + + DRONE + + APPVEYOR + +end + """ deploydocs( root = "", @@ -381,7 +409,8 @@ hide(root::AbstractString, children) = (true, nothing, root, map(hide, children) make = nothing | , devbranch = "master", devurl = "dev", - versions = ["stable" => "v^", "v#.#", devurl => devurl] + versions = ["stable" => "v^", "v#.#", devurl => devurl], + uploader = TRAVIS ) Converts markdown files generated by [`makedocs`](@ref) to HTML and pushes them to `repo`. @@ -463,7 +492,7 @@ the generated html. The following entries are valied in the `versions` vector: (as in e.g. `"stable" => "v^"`). **uploader** determines _which_ CI service will upload the documentation. Defaults to Travis -(`"TRAVIS"`). Other options are `"GITLAB_CI"`, `"CIRRUS_CI"`, `"DRONE"`, and `"APPVEYOR"`. +(`TRAVIS`). Other options are `GITLAB_CI`, `CIRRUS_CI`, `DRONE`, and `APPVEYOR`. # Environment variables @@ -528,7 +557,7 @@ function deploydocs(; devurl = "dev", versions = ["stable" => "v^", "v#.#", devurl => devurl], forcepush::Bool = false, - uploader = "TRAVIS" + uploader::CI_SYSTEM = TRAVIS ) # deprecation of latest kwarg (renamed to devbranch) if latest !== nothing @@ -539,7 +568,7 @@ function deploydocs(; # deprecation/removal of `julia` and `osname` kwargs if julia !== nothing Base.depwarn("the `julia` keyword argument to `Documenter.deploydocs` is " * - "removed. Use Travis Build Stages for determining from where to deploy instead. " * + "removed. Use CI Build Stages for determining from where to deploy instead. " * "See the section about Hosting in the Documenter manual for more details.", :deploydocs) @info "skipping docs deployment." return @@ -552,7 +581,7 @@ function deploydocs(; return end - local finaldeploy + local branch, pull_request, repo_slug, tag, event_type, finaldeploy if haskey(ENV, "CI") @@ -566,7 +595,7 @@ function deploydocs(; tag = get(ENV, "TRAVIS_TAG", "") event_type = get(ENV, "TRAVIS_EVENT_TYPE", "") - finaldeploy = uploader == "TRAVIS" + finaldeploy = uploader == TRAVIS elseif haskey(ENV, "GITLAB_CI") @@ -578,7 +607,7 @@ function deploydocs(; tag = get(ENV, "CI_COMMIT_TAG", "") event_type = get(ENV, "CI_PIPELINE_SOURCE", "") - finaldeploy = uploader == "GITLAB_CI" + finaldeploy = uploader == GITLAB_CI elseif haskey(ENV, "DRONE") @@ -590,7 +619,7 @@ function deploydocs(; tag = get(ENV, "DRONE_TAG", "") event_type = get(ENV, "DRONE_BUILD_EVENT", "") - finaldeploy = uploader == "DRONE" + finaldeploy = uploader == DRONE elseif haskey(ENV, "CIRRUS_CI") @@ -602,7 +631,7 @@ function deploydocs(; tag = get(ENV, "CIRRUS_TAG", "") event_type = "unknown" # Cirrus CI doesn't seem to provide the triggering event... - finaldeploy = uploader == "CIRRUS_CI" + finaldeploy = uploader == CIRRUS_CI elseif haskey(ENV, "APPVEYOR") # the worst of them all @@ -618,14 +647,14 @@ function deploydocs(; tag = get(ENV, "APPVEYOR_REPO_TAG_NAME", "") event_type = "unknown" # Appveyor has four env vars for this... - finaldeploy = uploader == "APPVEYOR" + finaldeploy = uploader == APPVEYOR else error( """ We don't recognize the CI service you're running, or haven't added support for it. - We currently support Travis-CI, Gitlab CI, Drone CI, Cirrus CI and AppVeyor. + We currently support Travis CI, Gitlab CI, Drone CI, Cirrus CI and AppVeyor. """ ) From 3bef32b5750dc76d73210decbcc0f58bbfe6d1e7 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 14 Jul 2019 07:19:06 +0530 Subject: [PATCH 07/25] Document and add CHANGELOG --- CHANGELOG.md | 2 ++ docs/src/man/hosting.md | 13 ++++++++++--- docs/src/man/hosting/walkthrough.md | 5 +++-- 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0436cecdf7..ed3a685bdc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,8 @@ * ![Experimental][badge-experimental] ![Feature][badge-feature] The current working directory when evaluating `@repl` and `@example` blocks can now be set to a fixed directory by passing the `workdir` keyword to `makedocs`. _The new keyword and its behaviour are experimental and not part of the public API._ ([#1013][github-1013], [#1025][github-1025]) +* ![Experimental][badge-experimantal] ![Feature][badge-feature] `deploydocs` now reads the appropriate environment variables on Travis CI, Gitlab CI, Cirrus CI, Drone CI, and AppVeyor, as does `LaTeXWriter`. + ## Version `v0.22.5` * ![Maintenance][badge-maintenance] Fix a test dependency problem revealed by a bugfix in Julia / Pkg. ([#1037][github-1037]) diff --git a/docs/src/man/hosting.md b/docs/src/man/hosting.md index e9bb4f7c41..eee3a7af6c 100644 --- a/docs/src/man/hosting.md +++ b/docs/src/man/hosting.md @@ -2,10 +2,17 @@ After going through the [Package Guide](@ref) and [Doctests](@ref) page you will need to host the generated documentation somewhere for potential users to read. This guide will -describe how to setup automatic updates for your package docs using the Travis build service +describe how to setup automatic updates for your package docs using CI build services and GitHub Pages. This is the same approach used by this package to host its own docs -- the docs you're currently reading. +!!! warning + + Documenter.jl only supports Travis CI, Gitlab CI, Cirrus CI, Drone CI, and AppVeyor. + + If you want to use another CI service, please either [open an issue](https://github.com/JuliaDocs/Documenter.jl/issues/new) + or set the relevant environment variables yourself. + !!! note Following this guide should be the *final* step you take after you are comfortable with @@ -14,8 +21,8 @@ the docs you're currently reading. documentation locally with Documenter. This guide assumes that you already have [GitHub](https://github.com/) and - [Travis](https://travis-ci.com/) accounts setup. If not then go set those up first and - then return here. + a CI system, like [Travis](https://travis-ci.com/) accounts setup. If not, + then go set those up first and then return here. ## Overview diff --git a/docs/src/man/hosting/walkthrough.md b/docs/src/man/hosting/walkthrough.md index f669c05afa..cb490e0c77 100644 --- a/docs/src/man/hosting/walkthrough.md +++ b/docs/src/man/hosting/walkthrough.md @@ -45,7 +45,7 @@ julia> read("privatekey", String) |> base64encode |> println ``` Copy and paste the output somewhere. This is your *private key* and is required for the step -[Adding the Private Key to Travis](@ref). +[Adding the Private Key to CI](@ref). Now we need to get the public key. Run the following command: @@ -128,7 +128,8 @@ to GitHub. The next step is to add the private key to Travis. In this section, we explain how to upload a private SSH key to Travis. By this point, you should have generated a private key and saved it to a file. If you haven't done this, go -read [Generating an SSH Key](@ref). +read [Generating an SSH Key](@ref). If you are using a different CI system, you will need +to do something else - consult your CI system's documentation. First, we need to Base64 encode the private key. Open Julia, and run the command From 2175bb116a38a10bcbf5d2ad67fe306ae7c2ded5 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 14 Jul 2019 14:10:19 +0530 Subject: [PATCH 08/25] fix overlapping variable names --- src/Documenter.jl | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index 454dd4b227..b9df17206a 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -581,7 +581,7 @@ function deploydocs(; return end - local branch, pull_request, repo_slug, tag, event_type, finaldeploy + local cibranch, pull_request, repo_slug, tag, event_type, finaldeploy if haskey(ENV, "CI") @@ -589,7 +589,7 @@ function deploydocs(; @info "Travis CI detected" - branch = get(ENV, "TRAVIS_BRANCH", "") + cibranch = get(ENV, "TRAVIS_BRANCH", "") pull_request = get(ENV, "TRAVIS_PULL_REQUEST", "") repo_slug = get(ENV, "TRAVIS_REPO_SLUG", "") tag = get(ENV, "TRAVIS_TAG", "") @@ -601,7 +601,7 @@ function deploydocs(; @info "Gitlab CI detected" - branch = get(ENV, "CI_COMMIT_REF_NAME", "") + cibranch = get(ENV, "CI_COMMIT_REF_NAME", "") pull_request = get(ENV, "CI_MERGE_REQUEST_ID", "false") repo_slug = get(ENV, "CI_PROJECT_PATH", "") tag = get(ENV, "CI_COMMIT_TAG", "") @@ -613,7 +613,7 @@ function deploydocs(; @info "Drone CI detected" - branch = get(ENV, "DRONE_COMMIT_BRANCH", "") + cibranch = get(ENV, "DRONE_COMMIT_BRANCH", "") pull_request = get(ENV, "DRONE_PULL_REQUEST", "false") repo_slug = get(ENV, "DRONE_REPO_NAMESPACE", "") * "/" * get(ENV, "DRONE_REPO_NAME", "") tag = get(ENV, "DRONE_TAG", "") @@ -625,7 +625,7 @@ function deploydocs(; @info "Cirrus CI detected" - branch = get(ENV, "CIRRUS_BRANCH", "") + cibranch = get(ENV, "CIRRUS_BRANCH", "") pull_request = get(ENV, "CIRRUS_PR", "false") repo_slug = get(ENV, "CIRRUS_REPO_FULL_NAME", "") tag = get(ENV, "CIRRUS_TAG", "") @@ -638,7 +638,7 @@ function deploydocs(; @info "AppVeyor CI detected" pull_request = get(ENV, "APPVEYOR_PULL_REQUEST_NUMBER", "false") - branch = if haskey(ENV, "APPVEYOR_PULL_REQUEST_NUMBER" ) + cibranch = if haskey(ENV, "APPVEYOR_PULL_REQUEST_NUMBER" ) ENV["APPVEYOR_PULL_REQUEST_HEAD_REPO_BRANCH"] else get(ENV, "APPVEYOR_REPO_BRANCH", "") @@ -691,7 +691,7 @@ function deploydocs(; ## If a tag exists, it should be a valid VersionNumber tag_ok = isempty(tag) || occursin(Base.VERSION_REGEX, tag) ## If no tag exists deploydocs' devbranch should match the CI branch - branch_ok = !isempty(tag) || branch == devbranch + branch_ok = !isempty(tag) || cibranch == devbranch ## DOCUMENTER_KEY should exist key_ok = !isempty(documenter_key) ## Cron jobs should not deploy @@ -704,7 +704,7 @@ function deploydocs(; - $(marker(repo_ok)) CI repo slug = "$(repo_slug)" occurs in repo = "$(repo)" - $(marker(pr_ok)) CI pull request indicator = "$(pull_request)" is "false" or "False" - $(marker(tag_ok)) CI tag indicator = "$(tag)" is (i) empty or (ii) a valid VersionNumber - - $(marker(branch_ok)) CI branch = "$(branch)" matches devbranch="$(devbranch)" (if tag is empty) + - $(marker(branch_ok)) CI branch = "$(cibranch)" matches devbranch="$(devbranch)" (if tag is empty) - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists - $(marker(type_ok)) CI event type = "$(event_type)" is not "cron" - $(marker(finaldeploy)) CI service is $uploader From 06422a8f7302bc4cddc8375ce4e91a9821465955 Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Mon, 15 Jul 2019 09:36:33 +1200 Subject: [PATCH 09/25] Add PR nr, don't have it experimental --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ed3a685bdc..7f4161057e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,8 @@ * ![Enhancement][badge-enhancement] Videos can now be included in the HTML output using the image syntax (`![]()`) if the file extension matches a known format (`.webm`, `.mp4`, `.ogg`, `.ogm`, `.ogv`, `.avi`). ([#1034][github-1034]) +* ![Enhancement][badge-enhancement] `deploydocs` now reads the appropriate environment variables on Travis CI, Gitlab CI, Cirrus CI, Drone CI, and AppVeyor, as does `LaTeXWriter`. ([#1067][github-1067]) + * ![Bugfix][badge-bugfix] The HTML output now outputs HTML files for pages that are not referenced in the `pages` keyword too (Documenter finds them according to their extension). But they do exists outside of the standard navigation hierarchy (as defined by `pages`). This fixes a bug where these pages could still be referenced by `@ref` links and `@contents` blocks, but in the HTML output, the links ended up being broken. ([#1031][github-1031], [#1047][github-1047]) * ![Bugfix][badge-bugfix] `makedocs` now throws an error when the format objects (`Documenter.HTML`, `LaTeX`, `Markdown`) get passed positionally. The format types are no longer subtypes of `Documenter.Plugin`. ([#1046][github-1046], [#1061][github-1061]) @@ -36,8 +38,6 @@ * ![Experimental][badge-experimental] ![Feature][badge-feature] The current working directory when evaluating `@repl` and `@example` blocks can now be set to a fixed directory by passing the `workdir` keyword to `makedocs`. _The new keyword and its behaviour are experimental and not part of the public API._ ([#1013][github-1013], [#1025][github-1025]) -* ![Experimental][badge-experimantal] ![Feature][badge-feature] `deploydocs` now reads the appropriate environment variables on Travis CI, Gitlab CI, Cirrus CI, Drone CI, and AppVeyor, as does `LaTeXWriter`. - ## Version `v0.22.5` * ![Maintenance][badge-maintenance] Fix a test dependency problem revealed by a bugfix in Julia / Pkg. ([#1037][github-1037]) @@ -377,6 +377,7 @@ [github-1054]: https://github.com/JuliaDocs/Documenter.jl/pull/1054 [github-1061]: https://github.com/JuliaDocs/Documenter.jl/pull/1061 [github-1062]: https://github.com/JuliaDocs/Documenter.jl/pull/1062 +[github-1067]: https://github.com/JuliaDocs/Documenter.jl/pull/1067 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl From b4c7620634f45db2bc235c8835d0ccfd459ecf31 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Mon, 15 Jul 2019 07:42:06 +0530 Subject: [PATCH 10/25] Remove exp badge, add untested info Co-Authored-By: Morten Piibeleht --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f4161057e..3daa8c9993 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,7 +26,7 @@ * ![Enhancement][badge-enhancement] Videos can now be included in the HTML output using the image syntax (`![]()`) if the file extension matches a known format (`.webm`, `.mp4`, `.ogg`, `.ogm`, `.ogv`, `.avi`). ([#1034][github-1034]) -* ![Enhancement][badge-enhancement] `deploydocs` now reads the appropriate environment variables on Travis CI, Gitlab CI, Cirrus CI, Drone CI, and AppVeyor, as does `LaTeXWriter`. ([#1067][github-1067]) +* ![Enhancement][badge-enhancement] `deploydocs` now reads the appropriate environment variables on Travis CI, Gitlab CI, Cirrus CI, Drone CI, and AppVeyor, as does `LaTeXWriter`. However, be aware that CI systems other than Travis CI have not received extensive testing. ([#1067][github-1067]) * ![Bugfix][badge-bugfix] The HTML output now outputs HTML files for pages that are not referenced in the `pages` keyword too (Documenter finds them according to their extension). But they do exists outside of the standard navigation hierarchy (as defined by `pages`). This fixes a bug where these pages could still be referenced by `@ref` links and `@contents` blocks, but in the HTML output, the links ended up being broken. ([#1031][github-1031], [#1047][github-1047]) From 1ef6c5caf38d3467f113d10cf1725214818e77ae Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Mon, 15 Jul 2019 21:06:15 +0530 Subject: [PATCH 11/25] read CI env in fcn, better manual deploy --- src/Documenter.jl | 230 +++++++++++++++++++++++-------------- src/Writers/LaTeXWriter.jl | 24 +--- 2 files changed, 147 insertions(+), 107 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index b9df17206a..7e699a87aa 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -399,6 +399,112 @@ Values: end +""" + read_ci_env([returnfinaldeploy::Bool]; uploader::CISystem = TRAVIS) + +Read the CI environment variables, and return (always) an Array where the first +five elements are, in order: + - `cibranch`: which branch is CI running on? + - `pull_request`: is CI building a pull request? Empty string if not. + - `repo_slug`: The URL-friendly repo name. + - `tag`: The tag being built bu CI. Empty string if not. + - `event_type`: The event that triggered CI. +Furthermore, if `returnfinaldeploy` is true, the function will check whether the +current CI provider matches `uploader` (set by default to Travis). +""" +function read_ci_env(returnfinaldeploy=false; uploader::CISystem = TRAVIS) + + arraylength = returnfinaldeploy ? 6 : 5 + + ret = Array{Union{String, Bool}}(undef, arraylength) + + if haskey(ENV, "TRAVIS") + + @info "Travis CI detected" + + cibranch = get(ENV, "TRAVIS_BRANCH", "") + pull_request = get(ENV, "TRAVIS_PULL_REQUEST", "") + repo_slug = get(ENV, "TRAVIS_REPO_SLUG", "") + tag = get(ENV, "TRAVIS_TAG", "") + event_type = get(ENV, "TRAVIS_EVENT_TYPE", "") + + ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) + + returnfinaldeploy && begin ret[6] = uploader == TRAVIS end + + elseif haskey(ENV, "GITLAB_CI") + + @info "Gitlab CI detected" + + cibranch = get(ENV, "CI_COMMIT_REF_NAME", "") + pull_request = get(ENV, "CI_MERGE_REQUEST_ID", "false") + repo_slug = get(ENV, "CI_PROJECT_PATH", "") + tag = get(ENV, "CI_COMMIT_TAG", "") + event_type = get(ENV, "CI_PIPELINE_SOURCE", "") + + ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) + + returnfinaldeploy && begin ret[6] = uploader == GITLAB_CI end + + elseif haskey(ENV, "DRONE") + + @info "Drone CI detected" + + cibranch = get(ENV, "DRONE_COMMIT_BRANCH", "") + pull_request = get(ENV, "DRONE_PULL_REQUEST", "false") + repo_slug = get(ENV, "DRONE_REPO_NAMESPACE", "") * "/" * get(ENV, "DRONE_REPO_NAME", "") + tag = get(ENV, "DRONE_TAG", "") + event_type = get(ENV, "DRONE_BUILD_EVENT", "") + + ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) + + returnfinaldeploy && begin ret[6] = uploader == DRONE end + + elseif haskey(ENV, "CIRRUS_CI") + + @info "Cirrus CI detected" + + cibranch = get(ENV, "CIRRUS_BRANCH", "") + pull_request = get(ENV, "CIRRUS_PR", "false") + repo_slug = get(ENV, "CIRRUS_REPO_FULL_NAME", "") + tag = get(ENV, "CIRRUS_TAG", "") + event_type = "unknown" # Cirrus CI doesn't seem to provide the triggering event... + + ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) + + returnfinaldeploy && begin ret[6] = uploader == CIRRUS_CI end + + elseif haskey(ENV, "APPVEYOR") # the worst of them all + + @info "AppVeyor CI detected" + + pull_request = get(ENV, "APPVEYOR_PULL_REQUEST_NUMBER", "false") + cibranch = if haskey(ENV, "APPVEYOR_PULL_REQUEST_NUMBER" ) + ENV["APPVEYOR_PULL_REQUEST_HEAD_REPO_BRANCH"] + else + get(ENV, "APPVEYOR_REPO_BRANCH", "") + end + repo_slug = get(ENV, "APPVEYOR_PROJECT_SLUG", "") + tag = get(ENV, "APPVEYOR_REPO_TAG_NAME", "") + event_type = "unknown" # Appveyor has four env vars for this... + + ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) + + returnfinaldeploy && begin ret[6] = uploader == APPVEYOR end + + else + + error( + """ + We don't recognize the CI service you're running, or haven't added support for it. + We currently support Travis CI, Gitlab CI, Drone CI, Cirrus CI and AppVeyor. + """ + ) + + end +end + + """ deploydocs( root = "", @@ -410,7 +516,8 @@ end devbranch = "master", devurl = "dev", versions = ["stable" => "v^", "v#.#", devurl => devurl], - uploader = TRAVIS + uploader = TRAVIS, + tag = "" # or "v*.*" if you want a specific tag ) Converts markdown files generated by [`makedocs`](@ref) to HTML and pushes them to `repo`. @@ -494,6 +601,12 @@ the generated html. The following entries are valied in the `versions` vector: **uploader** determines _which_ CI service will upload the documentation. Defaults to Travis (`TRAVIS`). Other options are `GITLAB_CI`, `CIRRUS_CI`, `DRONE`, and `APPVEYOR`. +**tag** provides a specific tag, if you want one to be set. Providing an empty string (if +building manually) will make the documentation build as if there was no tag; but, if run on +CI, it will read the appropriate environment variable to determine if a tag exists or not; +if there is a provided tag, then that will take precedence over the environment variable, +which will take precedence over the empty string. + # Environment variables - **`DOCUMENTER_KEY`**: must contain the Base64-encoded SSH private key for the repository. @@ -584,82 +697,14 @@ function deploydocs(; local cibranch, pull_request, repo_slug, tag, event_type, finaldeploy if haskey(ENV, "CI") - - if haskey(ENV, "TRAVIS") - - @info "Travis CI detected" - - cibranch = get(ENV, "TRAVIS_BRANCH", "") - pull_request = get(ENV, "TRAVIS_PULL_REQUEST", "") - repo_slug = get(ENV, "TRAVIS_REPO_SLUG", "") - tag = get(ENV, "TRAVIS_TAG", "") - event_type = get(ENV, "TRAVIS_EVENT_TYPE", "") - - finaldeploy = uploader == TRAVIS - - elseif haskey(ENV, "GITLAB_CI") - - @info "Gitlab CI detected" - - cibranch = get(ENV, "CI_COMMIT_REF_NAME", "") - pull_request = get(ENV, "CI_MERGE_REQUEST_ID", "false") - repo_slug = get(ENV, "CI_PROJECT_PATH", "") - tag = get(ENV, "CI_COMMIT_TAG", "") - event_type = get(ENV, "CI_PIPELINE_SOURCE", "") - - finaldeploy = uploader == GITLAB_CI - - elseif haskey(ENV, "DRONE") - - @info "Drone CI detected" - - cibranch = get(ENV, "DRONE_COMMIT_BRANCH", "") - pull_request = get(ENV, "DRONE_PULL_REQUEST", "false") - repo_slug = get(ENV, "DRONE_REPO_NAMESPACE", "") * "/" * get(ENV, "DRONE_REPO_NAME", "") - tag = get(ENV, "DRONE_TAG", "") - event_type = get(ENV, "DRONE_BUILD_EVENT", "") - - finaldeploy = uploader == DRONE - - elseif haskey(ENV, "CIRRUS_CI") - - @info "Cirrus CI detected" - - cibranch = get(ENV, "CIRRUS_BRANCH", "") - pull_request = get(ENV, "CIRRUS_PR", "false") - repo_slug = get(ENV, "CIRRUS_REPO_FULL_NAME", "") - tag = get(ENV, "CIRRUS_TAG", "") - event_type = "unknown" # Cirrus CI doesn't seem to provide the triggering event... - - finaldeploy = uploader == CIRRUS_CI - - elseif haskey(ENV, "APPVEYOR") # the worst of them all - - @info "AppVeyor CI detected" - - pull_request = get(ENV, "APPVEYOR_PULL_REQUEST_NUMBER", "false") - cibranch = if haskey(ENV, "APPVEYOR_PULL_REQUEST_NUMBER" ) - ENV["APPVEYOR_PULL_REQUEST_HEAD_REPO_BRANCH"] - else - get(ENV, "APPVEYOR_REPO_BRANCH", "") - end - repo_slug = get(ENV, "APPVEYOR_PROJECT_SLUG", "") - tag = get(ENV, "APPVEYOR_REPO_TAG_NAME", "") - event_type = "unknown" # Appveyor has four env vars for this... - - finaldeploy = uploader == APPVEYOR - - else - - error( - """ - We don't recognize the CI service you're running, or haven't added support for it. - We currently support Travis CI, Gitlab CI, Drone CI, Cirrus CI and AppVeyor. - """ - ) - - end - + cibranch, pull_request, repo_slug, tag, event_type, finaldeploy = read_ci_env(true, uploader=uploader) + else + cibranch = devbranch + pull_request = false + repo_slug = repo + tag = isempty(tag) && read_ci_env()[4] + event_type = "manual" + finaldeploy = haskey(ENV, "DOCUMENTER_KEY") end # Get environment variables. @@ -700,16 +745,27 @@ function deploydocs(; should_deploy = repo_ok && pr_ok && tag_ok && branch_ok && key_ok && type_ok && finaldeploy marker(x) = x ? "✔" : "✘" - @info """Deployment criteria: - - $(marker(repo_ok)) CI repo slug = "$(repo_slug)" occurs in repo = "$(repo)" - - $(marker(pr_ok)) CI pull request indicator = "$(pull_request)" is "false" or "False" - - $(marker(tag_ok)) CI tag indicator = "$(tag)" is (i) empty or (ii) a valid VersionNumber - - $(marker(branch_ok)) CI branch = "$(cibranch)" matches devbranch="$(devbranch)" (if tag is empty) - - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists - - $(marker(type_ok)) CI event type = "$(event_type)" is not "cron" - - $(marker(finaldeploy)) CI service is $uploader - Deploying: $(marker(should_deploy)) - """ + if HASKEY(ENV, "CI") + @info """ + Deploying on CI. + Deployment criteria: + - $(marker(repo_ok)) CI repo slug = "$(repo_slug)" occurs in repo = "$(repo)" + - $(marker(pr_ok)) CI pull request indicator = "$(pull_request)" is "false" or "False" + - $(marker(tag_ok)) CI tag indicator = "$(tag)" is (i) empty or (ii) a valid VersionNumber + - $(marker(branch_ok)) CI branch = "$(cibranch)" matches devbranch="$(devbranch)" (if tag is empty) + - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists + - $(marker(type_ok)) CI event type = "$(event_type)" is not "cron" + - $(marker(finaldeploy)) CI service is $uploader + Deploying: $(marker(should_deploy)) + """ + else + @info """ + Deploying manually. + Deployment criteria: + - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists + Deploying: $(marker(should_deploy)) + """ + end if should_deploy # Add local bin path if needed. diff --git a/src/Writers/LaTeXWriter.jl b/src/Writers/LaTeXWriter.jl index 6d7539b2a7..4d8f91f9f8 100644 --- a/src/Writers/LaTeXWriter.jl +++ b/src/Writers/LaTeXWriter.jl @@ -203,26 +203,10 @@ function writeheader(io::IO, doc::Documents.Document) isfile(custom) ? cp(custom, "custom.sty"; force = true) : touch("custom.sty") tag = if haskey(ENV, "CI") - if haskey(ENV, "TRAVIS") - @info "Travis CI detected" - get(ENV, "TRAVIS_TAG", "") - elseif haskey(ENV, "GITLAB_CI") - @info "Gitlab CI detected" - get(ENV, "CI_COMMIT_TAG", "") - elseif haskey(ENV, "DRONE") - @info "Drone CI detected" - get(ENV, "DRONE_TAG", "") - elseif haskey(ENV, "CIRRUS_CI") - @info "Cirrus CI detected" - get(ENV, "CIRRUS_TAG", "") - elseif haskey(ENV, "APPVEYOR") - @info "AppVeyor CI detected" - get(ENV, "APPVEYOR_REPO_TAG_NAME", "") - end - @info "No tag detected..." - else - "" - end + read_ci_env(false)[4] + else + "" + end preamble = """ \\documentclass{memoir} From 17acc6685ff46a26152f37e0e285d77651d2d762 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Mon, 15 Jul 2019 21:18:26 +0530 Subject: [PATCH 12/25] FIX TYPE --- src/Documenter.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index 7e699a87aa..fbe96c4e6b 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -400,7 +400,7 @@ Values: end """ - read_ci_env([returnfinaldeploy::Bool]; uploader::CISystem = TRAVIS) + read_ci_env([returnfinaldeploy::Bool]; uploader::CI_SYSTEM = TRAVIS) Read the CI environment variables, and return (always) an Array where the first five elements are, in order: @@ -412,7 +412,7 @@ five elements are, in order: Furthermore, if `returnfinaldeploy` is true, the function will check whether the current CI provider matches `uploader` (set by default to Travis). """ -function read_ci_env(returnfinaldeploy=false; uploader::CISystem = TRAVIS) +function read_ci_env(returnfinaldeploy=false; uploader::CI_SYSTEM = TRAVIS) arraylength = returnfinaldeploy ? 6 : 5 From 0dea97038365ee2c8a0d2c755ba0cf538d78b358 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Tue, 16 Jul 2019 07:14:32 +0530 Subject: [PATCH 13/25] Apply suggestions from review Co-Authored-By: Morten Piibeleht --- src/Documenter.jl | 212 +++++++++++++++++++------------------ src/Writers/LaTeXWriter.jl | 29 +---- 2 files changed, 113 insertions(+), 128 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index fbe96c4e6b..5e53427326 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -386,23 +386,17 @@ Values: * `APPVEYOR` """ @enum CI_SYSTEM begin - TRAVIS - GITLAB_CI - CIRRUS_CI - DRONE - APPVEYOR - end """ read_ci_env([returnfinaldeploy::Bool]; uploader::CI_SYSTEM = TRAVIS) -Read the CI environment variables, and return (always) an Array where the first +Read the CI environment variables, and return (always) a NamedTuple where the first five elements are, in order: - `cibranch`: which branch is CI running on? - `pull_request`: is CI building a pull request? Empty string if not. @@ -411,12 +405,14 @@ five elements are, in order: - `event_type`: The event that triggered CI. Furthermore, if `returnfinaldeploy` is true, the function will check whether the current CI provider matches `uploader` (set by default to Travis). + +Returns a NamedTuple. """ function read_ci_env(returnfinaldeploy=false; uploader::CI_SYSTEM = TRAVIS) arraylength = returnfinaldeploy ? 6 : 5 - ret = Array{Union{String, Bool}}(undef, arraylength) + ret = nothing if haskey(ENV, "TRAVIS") @@ -428,9 +424,9 @@ function read_ci_env(returnfinaldeploy=false; uploader::CI_SYSTEM = TRAVIS) tag = get(ENV, "TRAVIS_TAG", "") event_type = get(ENV, "TRAVIS_EVENT_TYPE", "") - ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) + ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) - returnfinaldeploy && begin ret[6] = uploader == TRAVIS end + returnfinaldeploy && begin ret = (ret..., uploader = uploader == TRAVIS) end elseif haskey(ENV, "GITLAB_CI") @@ -442,9 +438,9 @@ function read_ci_env(returnfinaldeploy=false; uploader::CI_SYSTEM = TRAVIS) tag = get(ENV, "CI_COMMIT_TAG", "") event_type = get(ENV, "CI_PIPELINE_SOURCE", "") - ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) + ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) - returnfinaldeploy && begin ret[6] = uploader == GITLAB_CI end + returnfinaldeploy && begin ret = (ret..., uploader = uploader == GITLAB_CI) end elseif haskey(ENV, "DRONE") @@ -456,9 +452,9 @@ function read_ci_env(returnfinaldeploy=false; uploader::CI_SYSTEM = TRAVIS) tag = get(ENV, "DRONE_TAG", "") event_type = get(ENV, "DRONE_BUILD_EVENT", "") - ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) + ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) - returnfinaldeploy && begin ret[6] = uploader == DRONE end + returnfinaldeploy && begin ret = (ret..., uploader = uploader == DRONE) end elseif haskey(ENV, "CIRRUS_CI") @@ -488,19 +484,23 @@ function read_ci_env(returnfinaldeploy=false; uploader::CI_SYSTEM = TRAVIS) tag = get(ENV, "APPVEYOR_REPO_TAG_NAME", "") event_type = "unknown" # Appveyor has four env vars for this... - ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) + ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) - returnfinaldeploy && begin ret[6] = uploader == APPVEYOR end + returnfinaldeploy && begin ret = (ret..., uploader = uploader == APPVEYOR) end else - error( + warning( """ We don't recognize the CI service you're running, or haven't added support for it. We currently support Travis CI, Gitlab CI, Drone CI, Cirrus CI and AppVeyor. """ ) + ret = (cibranch = nothing, pull_request = nothing, repo_slug = nothing, tag = nothing, event_type = nothing) + + returnfinaldeploy && begin ret = (ret..., uploader = uploader == nothing) end + end end @@ -670,7 +670,8 @@ function deploydocs(; devurl = "dev", versions = ["stable" => "v^", "v#.#", devurl => devurl], forcepush::Bool = false, - uploader::CI_SYSTEM = TRAVIS + uploader::CI_SYSTEM = TRAVIS, + tag = "" ) # deprecation of latest kwarg (renamed to devbranch) if latest !== nothing @@ -697,12 +698,13 @@ function deploydocs(; local cibranch, pull_request, repo_slug, tag, event_type, finaldeploy if haskey(ENV, "CI") - cibranch, pull_request, repo_slug, tag, event_type, finaldeploy = read_ci_env(true, uploader=uploader) + cibranch, pull_request, repo_slug, citag, event_type, finaldeploy = read_ci_env(true, uploader=uploader) + tag = isempty(tag) ? citag : tag else cibranch = devbranch pull_request = false repo_slug = repo - tag = isempty(tag) && read_ci_env()[4] + tag = isempty(tag) ? read_ci_env()[:tag] : tag event_type = "manual" finaldeploy = haskey(ENV, "DOCUMENTER_KEY") end @@ -745,7 +747,7 @@ function deploydocs(; should_deploy = repo_ok && pr_ok && tag_ok && branch_ok && key_ok && type_ok && finaldeploy marker(x) = x ? "✔" : "✘" - if HASKEY(ENV, "CI") + if haskey(ENV, "CI") @info """ Deploying on CI. Deployment criteria: @@ -836,100 +838,106 @@ function git_push( end chmod(keyfile, 0o600) - try - # Use a custom SSH config file to avoid overwriting the default user config. - withfile(joinpath(homedir(), ".ssh", "config"), - """ - Host $host - StrictHostKeyChecking no - HostName $host - IdentityFile "$keyfile" - BatchMode yes - """ - ) do - cd(temp) do - # Setup git. - run(`git init`) - run(`git config user.name "zeptodoctor"`) - run(`git config user.email "44736852+zeptodoctor@users.noreply.github.com"`) - - # Fetch from remote and checkout the branch. - run(`git remote add upstream $upstream`) - try - run(`git fetch upstream`) - catch e - @error """ - Git failed to fetch $upstream - This can be caused by a DOCUMENTER_KEY variable that is not correctly set up. - Make sure that the environment variable is properly set up as a Base64-encoded string - of the SSH private key. You may need to re-generate the keys with DocumenterTools. - """ - rethrow(e) - end + function _push() + cd(temp) do + # Setup git. + run(`git init`) + run(`git config user.name "zeptodoctor"`) + run(`git config user.email "44736852+zeptodoctor@users.noreply.github.com"`) + + # Fetch from remote and checkout the branch. + run(`git remote add upstream $upstream`) + try + run(`git fetch upstream`) + catch e + @error """ + Git failed to fetch $upstream + This can be caused by a DOCUMENTER_KEY variable that is not correctly set up. + Make sure that the environment variable is properly set up as a Base64-encoded string + of the SSH private key. You may need to re-generate the keys with DocumenterTools. + """ + rethrow(e) + end - try - run(`git checkout -b $branch upstream/$branch`) - catch e - @debug "checking out $branch failed with error: $e" - @debug "creating a new local $branch branch." - run(`git checkout --orphan $branch`) - run(`git commit --allow-empty -m "Initial empty commit for docs"`) - end + try + run(`git checkout -b $branch upstream/$branch`) + catch e + @debug "checking out $branch failed with error: $e" + @debug "creating a new local $branch branch." + run(`git checkout --orphan $branch`) + run(`git commit --allow-empty -m "Initial empty commit for docs"`) + end - # Copy docs to `devurl`, or `stable`, ``, and `` directories. - if isempty(tag) - devurl_dir = joinpath(dirname, devurl) - gitrm_copy(target_dir, devurl_dir) - Writers.HTMLWriter.generate_siteinfo_file(devurl_dir, devurl) - # symlink "latest" to devurl to preserve links (remove in some future release) - if devurl != "latest" - rm(joinpath(dirname, "latest"); recursive = true, force = true) - @warn(string("creating symlink from `latest` to `$(devurl)` for backwards ", - "compatibility with old links. In future Documenter versions this symlink ", - "will not be created. Please update any links that point to `latest`.")) - cd(dirname) do; rm_and_add_symlink(devurl, "latest"); end - end - else - tagged_dir = joinpath(dirname, tag) - gitrm_copy(target_dir, tagged_dir) - Writers.HTMLWriter.generate_siteinfo_file(tagged_dir, tag) + # Copy docs to `devurl`, or `stable`, ``, and `` directories. + if isempty(tag) + devurl_dir = joinpath(dirname, devurl) + gitrm_copy(target_dir, devurl_dir) + Writers.HTMLWriter.generate_siteinfo_file(devurl_dir, devurl) + # symlink "latest" to devurl to preserve links (remove in some future release) + if devurl != "latest" + rm(joinpath(dirname, "latest"); recursive = true, force = true) + @warn(string("creating symlink from `latest` to `$(devurl)` for backwards ", + "compatibility with old links. In future Documenter versions this symlink ", + "will not be created. Please update any links that point to `latest`.")) + cd(dirname) do; rm_and_add_symlink(devurl, "latest"); end end + else + tagged_dir = joinpath(dirname, tag) + gitrm_copy(target_dir, tagged_dir) + Writers.HTMLWriter.generate_siteinfo_file(tagged_dir, tag) + end - # Expand the users `versions` vector - entries, symlinks = Writers.HTMLWriter.expand_versions(dirname, versions) + # Expand the users `versions` vector + entries, symlinks = Writers.HTMLWriter.expand_versions(dirname, versions) - # Create the versions.js file containing a list of `entries`. - # This must always happen after the folder copying. - Writers.HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries) + # Create the versions.js file containing a list of `entries`. + # This must always happen after the folder copying. + Writers.HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries) - # generate the symlinks, make sure we don't overwrite devurl - cd(dirname) do - for kv in symlinks - i = findfirst(x -> x.first == devurl, symlinks) - if i === nothing - rm_and_add_symlink(kv.second, kv.first) - else - throw(ArgumentError(string("link `$(kv)` cannot overwrite ", - "`devurl = $(devurl)` with the same name."))) - end + # generate the symlinks, make sure we don't overwrite devurl + cd(dirname) do + for kv in symlinks + i = findfirst(x -> x.first == devurl, symlinks) + if i === nothing + rm_and_add_symlink(kv.second, kv.first) + else + throw(ArgumentError(string("link `$(kv)` cannot overwrite ", + "`devurl = $(devurl)` with the same name."))) end end + end - # Add, commit, and push the docs to the remote. - run(`git add -A .`) - if !success(`git diff --cached --exit-code`) - if forcepush - run(`git commit --amend --date=now -m "build based on $sha"`) - run(`git push -fq upstream HEAD:$branch`) - else - run(`git commit -m "build based on $sha"`) - run(`git push -q upstream HEAD:$branch`) - end + # Add, commit, and push the docs to the remote. + run(`git add -A .`) + if !success(`git diff --cached --exit-code`) + if forcepush + run(`git commit --amend --date=now -m "build based on $sha"`) + run(`git push -fq upstream HEAD:$branch`) else - @debug "new docs identical to the old -- not committing nor pushing." + run(`git commit -m "build based on $sha"`) + run(`git push -q upstream HEAD:$branch`) end + else + @debug "new docs identical to the old -- not committing nor pushing." end end + end + + try + # Use a custom SSH config file to avoid overwriting the default user config. + if haskey(ENV, "CI") + withfile(_push, joinpath(homedir(), ".ssh", "config"), + """ + Host $host + StrictHostKeyChecking no + HostName $host + IdentityFile "$keyfile" + BatchMode yes + """ + ) + else + _push() + end finally # Remove the unencrypted private key. isfile(keyfile) && rm(keyfile) diff --git a/src/Writers/LaTeXWriter.jl b/src/Writers/LaTeXWriter.jl index 4d8f91f9f8..3375b88a9a 100644 --- a/src/Writers/LaTeXWriter.jl +++ b/src/Writers/LaTeXWriter.jl @@ -90,28 +90,9 @@ function render(doc::Documents.Document, settings::LaTeX=LaTeX()) cp(joinpath(doc.user.root, doc.user.build), joinpath(path, "build")) cd(joinpath(path, "build")) do name = doc.user.sitename - let tag = if haskey(ENV, "CI") - if haskey(ENV, "TRAVIS") - @info "Travis CI detected" - get(ENV, "TRAVIS_TAG", "") - elseif haskey(ENV, "GITLAB_CI") - @info "Gitlab CI detected" - get(ENV, "CI_COMMIT_TAG", "") - elseif haskey(ENV, "DRONE") - @info "Drone CI detected" - get(ENV, "DRONE_TAG", "") - elseif haskey(ENV, "CIRRUS_CI") - @info "Cirrus CI detected" - get(ENV, "CIRRUS_TAG", "") - elseif haskey(ENV, "APPVEYOR") - @info "AppVeyor CI detected" - get(ENV, "APPVEYOR_REPO_TAG_NAME", "") - end - else - "" - end + let tag = read_ci_env()[:tag] - if occursin(Base.VERSION_REGEX, tag) + if occursin(Base.VERSION_REGEX, tag === nothing ? "" : tag) v = VersionNumber(tag) name *= "-$(v.major).$(v.minor).$(v.patch)" end @@ -202,11 +183,7 @@ function writeheader(io::IO, doc::Documents.Document) custom = joinpath(doc.user.root, doc.user.source, "assets", "custom.sty") isfile(custom) ? cp(custom, "custom.sty"; force = true) : touch("custom.sty") - tag = if haskey(ENV, "CI") - read_ci_env(false)[4] - else - "" - end + tag = haskey(ENV, "CI") ? read_ci_env(false)[4] : "" preamble = """ \\documentclass{memoir} From 26c5affa91cdb9c33b6d87afe64a4354fbe9524f Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Tue, 16 Jul 2019 07:18:47 +0530 Subject: [PATCH 14/25] Add functions to docs (wow that was easy) --- docs/src/lib/internals/documenter.md | 1 + docs/src/lib/public.md | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/src/lib/internals/documenter.md b/docs/src/lib/internals/documenter.md index de28117576..db531cee3e 100644 --- a/docs/src/lib/internals/documenter.md +++ b/docs/src/lib/internals/documenter.md @@ -3,4 +3,5 @@ ```@docs Documenter.gitrm_copy Documenter.git_push +read_ci_env ``` diff --git a/docs/src/lib/public.md b/docs/src/lib/public.md index 7231b11d25..ed50aa7739 100644 --- a/docs/src/lib/public.md +++ b/docs/src/lib/public.md @@ -22,6 +22,7 @@ Pages = ["public.md"] Documenter makedocs hide +CI_SYSTEM deploydocs Deps Deps.pip From edbf3435d15fba1b7e0732a28bb3f3efe0184504 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Tue, 16 Jul 2019 11:32:35 +0530 Subject: [PATCH 15/25] Fix misuse of tag --- src/Documenter.jl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index 5e53427326..73a3b9a129 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -695,16 +695,16 @@ function deploydocs(; return end - local cibranch, pull_request, repo_slug, tag, event_type, finaldeploy + local cibranch, pull_request, repo_slug, localtag, event_type, finaldeploy if haskey(ENV, "CI") cibranch, pull_request, repo_slug, citag, event_type, finaldeploy = read_ci_env(true, uploader=uploader) - tag = isempty(tag) ? citag : tag + localtag = isempty(tag) ? citag : tag else cibranch = devbranch pull_request = false repo_slug = repo - tag = isempty(tag) ? read_ci_env()[:tag] : tag + localtag = isempty(tag) ? read_ci_env()[:tag] : tag event_type = "manual" finaldeploy = haskey(ENV, "DOCUMENTER_KEY") end @@ -736,7 +736,7 @@ function deploydocs(; ## Do not deploy for PRs pr_ok = pull_request in ("false", "False") # Appveyor env vars are capitalized on Windows ## If a tag exists, it should be a valid VersionNumber - tag_ok = isempty(tag) || occursin(Base.VERSION_REGEX, tag) + tag_ok = isempty(localtag) || occursin(Base.VERSION_REGEX, tag) ## If no tag exists deploydocs' devbranch should match the CI branch branch_ok = !isempty(tag) || cibranch == devbranch ## DOCUMENTER_KEY should exist @@ -753,7 +753,7 @@ function deploydocs(; Deployment criteria: - $(marker(repo_ok)) CI repo slug = "$(repo_slug)" occurs in repo = "$(repo)" - $(marker(pr_ok)) CI pull request indicator = "$(pull_request)" is "false" or "False" - - $(marker(tag_ok)) CI tag indicator = "$(tag)" is (i) empty or (ii) a valid VersionNumber + - $(marker(tag_ok)) CI tag indicator = "$(localtag)" is (i) empty or (ii) a valid VersionNumber - $(marker(branch_ok)) CI branch = "$(cibranch)" matches devbranch="$(devbranch)" (if tag is empty) - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists - $(marker(type_ok)) CI event type = "$(event_type)" is not "cron" From 4ee8b8fa8670f574d7d00006f35b87a2ddfefa8d Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Wed, 17 Jul 2019 17:35:33 +1200 Subject: [PATCH 16/25] Fix bad link --- docs/src/man/hosting/walkthrough.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/man/hosting/walkthrough.md b/docs/src/man/hosting/walkthrough.md index 5386d8ff79..9cab33129b 100644 --- a/docs/src/man/hosting/walkthrough.md +++ b/docs/src/man/hosting/walkthrough.md @@ -47,7 +47,7 @@ julia> read("privatekey", String) |> base64encode |> println ``` Copy and paste the output somewhere. This is your *private key* and is required for the step -[Adding the Private Key to CI](@ref). +[Adding the Private Key to Travis](@ref). Now we need to get the public key. Run the following command: From cd753ed8a48f291b2b5d23db9892ab92c8b1904a Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Wed, 17 Jul 2019 17:56:47 +1200 Subject: [PATCH 17/25] Add CHANGELOG for tag change --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3daa8c9993..62b01b0b1c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,8 @@ * ![Enhancement][badge-enhancement] `deploydocs` now reads the appropriate environment variables on Travis CI, Gitlab CI, Cirrus CI, Drone CI, and AppVeyor, as does `LaTeXWriter`. However, be aware that CI systems other than Travis CI have not received extensive testing. ([#1067][github-1067]) +* ![Enhancement][badge-enhancement] `deploydocs` can now be switched to tag building mode with the `tag` keyword, which overrides the tag information from CI environment variables. ([#1067][github-1067]) + * ![Bugfix][badge-bugfix] The HTML output now outputs HTML files for pages that are not referenced in the `pages` keyword too (Documenter finds them according to their extension). But they do exists outside of the standard navigation hierarchy (as defined by `pages`). This fixes a bug where these pages could still be referenced by `@ref` links and `@contents` blocks, but in the HTML output, the links ended up being broken. ([#1031][github-1031], [#1047][github-1047]) * ![Bugfix][badge-bugfix] `makedocs` now throws an error when the format objects (`Documenter.HTML`, `LaTeX`, `Markdown`) get passed positionally. The format types are no longer subtypes of `Documenter.Plugin`. ([#1046][github-1046], [#1061][github-1061]) From f58f06f41e0b4309f9a7e0179fb54c5c1c32ac2b Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Wed, 17 Jul 2019 17:57:55 +1200 Subject: [PATCH 18/25] Add docs So, the DocStringExtensions' $EXPORTS in the Documenter module docstring creates at-ref links, so we need to make sure that we have docstrings available to all exported names. But you can't add docstrings in the at-enum, so I'm doing it separately. Also, add all the refs to those variables while we're at it. --- docs/src/lib/internals/documenter.md | 2 +- docs/src/lib/public.md | 12 +++++++++++- src/Documenter.jl | 26 +++++++++++++++++++------- 3 files changed, 31 insertions(+), 9 deletions(-) diff --git a/docs/src/lib/internals/documenter.md b/docs/src/lib/internals/documenter.md index db531cee3e..c73c3286f9 100644 --- a/docs/src/lib/internals/documenter.md +++ b/docs/src/lib/internals/documenter.md @@ -3,5 +3,5 @@ ```@docs Documenter.gitrm_copy Documenter.git_push -read_ci_env +Documenter.read_ci_env ``` diff --git a/docs/src/lib/public.md b/docs/src/lib/public.md index ed50aa7739..ff38e632f0 100644 --- a/docs/src/lib/public.md +++ b/docs/src/lib/public.md @@ -22,7 +22,6 @@ Pages = ["public.md"] Documenter makedocs hide -CI_SYSTEM deploydocs Deps Deps.pip @@ -32,6 +31,17 @@ DocMeta.getdocmeta DocMeta.setdocmeta! ``` +### CI platforms supported by `deploydocs` + +```@docs +Documenter.CI_SYSTEM +TRAVIS +GITLAB_CI +CIRRUS_CI +DRONE +APPVEYOR +``` + ## DocumenterTools ```@docs diff --git a/src/Documenter.jl b/src/Documenter.jl index 73a3b9a129..705ec7677b 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -379,11 +379,11 @@ hide(root::AbstractString, children) = (true, nothing, root, map(hide, children) The supported CI systems to deploy docs from, using Documenter.jl. Values: -* `TRAVIS` -* `GITLAB_CI` -* `CIRRUS_CI` -* `DRONE` -* `APPVEYOR` +* [`TRAVIS`](@ref) +* [`GITLAB_CI`](@ref) +* [`CIRRUS_CI`](@ref) +* [`DRONE`](@ref) +* [`APPVEYOR`](@ref) """ @enum CI_SYSTEM begin TRAVIS @@ -392,6 +392,17 @@ Values: DRONE APPVEYOR end +# docstrings for CI_SYSTEM values +"Specialize [`deploydocs`](@ref) for [Travis CI](https://travis-ci.org/). See also [`Documenter.CI_SYSTEM`](@ref)." +TRAVIS +"Specialize [`deploydocs`](@ref) for [Appveyor](https://www.appveyor.com/). See also [`Documenter.CI_SYSTEM`](@ref)." +APPVEYOR +"Specialize [`deploydocs`](@ref) for [GitLab CI](https://about.gitlab.com/product/continuous-integration/). See also [`Documenter.CI_SYSTEM`](@ref)." +GITLAB_CI +"Specialize [`deploydocs`](@ref) for [Cirrus CI](https://cirrus-ci.org/). See also [`Documenter.CI_SYSTEM`](@ref)." +CIRRUS_CI +"Specialize [`deploydocs`](@ref) for [Drone](https://drone.io/). See also [`Documenter.CI_SYSTEM`](@ref)." +DRONE """ read_ci_env([returnfinaldeploy::Bool]; uploader::CI_SYSTEM = TRAVIS) @@ -598,8 +609,9 @@ the generated html. The following entries are valied in the `versions` vector: The second argument can be `"v^"`, to point to the maximum version docs (as in e.g. `"stable" => "v^"`). -**uploader** determines _which_ CI service will upload the documentation. Defaults to Travis -(`TRAVIS`). Other options are `GITLAB_CI`, `CIRRUS_CI`, `DRONE`, and `APPVEYOR`. +**uploader** determines _which_ CI service will upload the documentation. Defaults to +Travis ([`TRAVIS`](@ref)). Other options are [`GITLAB_CI`](@ref), [`CIRRUS_CI`](@ref), +[`DRONE`](@ref), and [`APPVEYOR`](@ref). **tag** provides a specific tag, if you want one to be set. Providing an empty string (if building manually) will make the documentation build as if there was no tag; but, if run on From 07bca349d6d7726389ccb774584ec6b4ad909bcb Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Wed, 17 Jul 2019 17:59:38 +1200 Subject: [PATCH 19/25] warning doesn't exist + code style --- src/Documenter.jl | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index 705ec7677b..a06e5287a2 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -500,16 +500,11 @@ function read_ci_env(returnfinaldeploy=false; uploader::CI_SYSTEM = TRAVIS) returnfinaldeploy && begin ret = (ret..., uploader = uploader == APPVEYOR) end else - - warning( - """ + @warn """ We don't recognize the CI service you're running, or haven't added support for it. We currently support Travis CI, Gitlab CI, Drone CI, Cirrus CI and AppVeyor. """ - ) - ret = (cibranch = nothing, pull_request = nothing, repo_slug = nothing, tag = nothing, event_type = nothing) - returnfinaldeploy && begin ret = (ret..., uploader = uploader == nothing) end end From 588fc01626dfb30aa40896452d3ccee9d1bbc798 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Tue, 23 Jul 2019 09:14:09 +0530 Subject: [PATCH 20/25] Change to namedtuple return type --- src/Writers/LaTeXWriter.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Writers/LaTeXWriter.jl b/src/Writers/LaTeXWriter.jl index 3375b88a9a..7aa75d4b0a 100644 --- a/src/Writers/LaTeXWriter.jl +++ b/src/Writers/LaTeXWriter.jl @@ -183,7 +183,7 @@ function writeheader(io::IO, doc::Documents.Document) custom = joinpath(doc.user.root, doc.user.source, "assets", "custom.sty") isfile(custom) ? cp(custom, "custom.sty"; force = true) : touch("custom.sty") - tag = haskey(ENV, "CI") ? read_ci_env(false)[4] : "" + tag = haskey(ENV, "CI") ? read_ci_env(false)[:tag] : "" preamble = """ \\documentclass{memoir} From e550502ec10b97d7fb86f0885da2dc8e8b681f14 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Tue, 23 Jul 2019 09:14:42 +0530 Subject: [PATCH 21/25] Remove manual tag setting from changelog --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 62b01b0b1c..1ca18206cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,7 +28,6 @@ * ![Enhancement][badge-enhancement] `deploydocs` now reads the appropriate environment variables on Travis CI, Gitlab CI, Cirrus CI, Drone CI, and AppVeyor, as does `LaTeXWriter`. However, be aware that CI systems other than Travis CI have not received extensive testing. ([#1067][github-1067]) -* ![Enhancement][badge-enhancement] `deploydocs` can now be switched to tag building mode with the `tag` keyword, which overrides the tag information from CI environment variables. ([#1067][github-1067]) * ![Bugfix][badge-bugfix] The HTML output now outputs HTML files for pages that are not referenced in the `pages` keyword too (Documenter finds them according to their extension). But they do exists outside of the standard navigation hierarchy (as defined by `pages`). This fixes a bug where these pages could still be referenced by `@ref` links and `@contents` blocks, but in the HTML output, the links ended up being broken. ([#1031][github-1031], [#1047][github-1047]) From 844d1f44978f32e613e34d32f47b3005eea9522c Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Tue, 23 Jul 2019 09:15:32 +0530 Subject: [PATCH 22/25] Remove empty line in CHANGELOG.md --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ca18206cc..3daa8c9993 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,7 +28,6 @@ * ![Enhancement][badge-enhancement] `deploydocs` now reads the appropriate environment variables on Travis CI, Gitlab CI, Cirrus CI, Drone CI, and AppVeyor, as does `LaTeXWriter`. However, be aware that CI systems other than Travis CI have not received extensive testing. ([#1067][github-1067]) - * ![Bugfix][badge-bugfix] The HTML output now outputs HTML files for pages that are not referenced in the `pages` keyword too (Documenter finds them according to their extension). But they do exists outside of the standard navigation hierarchy (as defined by `pages`). This fixes a bug where these pages could still be referenced by `@ref` links and `@contents` blocks, but in the HTML output, the links ended up being broken. ([#1031][github-1031], [#1047][github-1047]) * ![Bugfix][badge-bugfix] `makedocs` now throws an error when the format objects (`Documenter.HTML`, `LaTeX`, `Markdown`) get passed positionally. The format types are no longer subtypes of `Documenter.Plugin`. ([#1046][github-1046], [#1061][github-1061]) From 51eb94f475e38cd4985e207141cb58eaf0593586 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Tue, 23 Jul 2019 09:47:10 +0530 Subject: [PATCH 23/25] Import `read_ci_env` to LaTeXWriter --- src/Writers/LaTeXWriter.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Writers/LaTeXWriter.jl b/src/Writers/LaTeXWriter.jl index 7aa75d4b0a..035e520315 100644 --- a/src/Writers/LaTeXWriter.jl +++ b/src/Writers/LaTeXWriter.jl @@ -13,7 +13,7 @@ navigation menu. It goes into the `\\title` LaTeX command. """ module LaTeXWriter -import ...Documenter: Documenter +import ...Documenter: Documenter, read_ci_env """ LaTeXWriter.LaTeX(; kwargs...) From 338d05d829942a2acc05d19b26de0cec2e7ed579 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Thu, 25 Jul 2019 13:23:40 +0530 Subject: [PATCH 24/25] Change structure so that LaTeXWriter can read CI variables --- src/CISystems.jl | 136 +++++++++++++++++++++++++++++++++++++++++++++ src/Documenter.jl | 139 +--------------------------------------------- 2 files changed, 137 insertions(+), 138 deletions(-) create mode 100644 src/CISystems.jl diff --git a/src/CISystems.jl b/src/CISystems.jl new file mode 100644 index 0000000000..94df9d7657 --- /dev/null +++ b/src/CISystems.jl @@ -0,0 +1,136 @@ +""" + enum CI_SYSTEM + +The supported CI systems to deploy docs from, using Documenter.jl. + +Values: +* [`TRAVIS`](@ref) +* [`GITLAB_CI`](@ref) +* [`CIRRUS_CI`](@ref) +* [`DRONE`](@ref) +* [`APPVEYOR`](@ref) +""" +@enum CI_SYSTEM begin + TRAVIS + GITLAB_CI + CIRRUS_CI + DRONE + APPVEYOR +end +# docstrings for CI_SYSTEM values +"Specialize [`deploydocs`](@ref) for [Travis CI](https://travis-ci.org/). See also [`Documenter.CI_SYSTEM`](@ref)." +TRAVIS +"Specialize [`deploydocs`](@ref) for [Appveyor](https://www.appveyor.com/). See also [`Documenter.CI_SYSTEM`](@ref)." +APPVEYOR +"Specialize [`deploydocs`](@ref) for [GitLab CI](https://about.gitlab.com/product/continuous-integration/). See also [`Documenter.CI_SYSTEM`](@ref)." +GITLAB_CI +"Specialize [`deploydocs`](@ref) for [Cirrus CI](https://cirrus-ci.org/). See also [`Documenter.CI_SYSTEM`](@ref)." +CIRRUS_CI +"Specialize [`deploydocs`](@ref) for [Drone](https://drone.io/). See also [`Documenter.CI_SYSTEM`](@ref)." +DRONE + +""" + read_ci_env([returnfinaldeploy::Bool]; uploader::CI_SYSTEM = TRAVIS) + +Read the CI environment variables, and return (always) a NamedTuple where the first +five elements are, in order: + - `cibranch`: which branch is CI running on? + - `pull_request`: is CI building a pull request? Empty string if not. + - `repo_slug`: The URL-friendly repo name. + - `tag`: The tag being built bu CI. Empty string if not. + - `event_type`: The event that triggered CI. +Furthermore, if `returnfinaldeploy` is true, the function will check whether the +current CI provider matches `uploader` (set by default to Travis). + +Returns a NamedTuple. +""" +function read_ci_env(returnfinaldeploy=false; uploader::CI_SYSTEM = TRAVIS) + + arraylength = returnfinaldeploy ? 6 : 5 + + ret = nothing + + if haskey(ENV, "TRAVIS") + + @info "Travis CI detected" + + cibranch = get(ENV, "TRAVIS_BRANCH", "") + pull_request = get(ENV, "TRAVIS_PULL_REQUEST", "") + repo_slug = get(ENV, "TRAVIS_REPO_SLUG", "") + tag = get(ENV, "TRAVIS_TAG", "") + event_type = get(ENV, "TRAVIS_EVENT_TYPE", "") + + ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) + + returnfinaldeploy && begin ret = (ret..., uploader = uploader == TRAVIS) end + + elseif haskey(ENV, "GITLAB_CI") + + @info "Gitlab CI detected" + + cibranch = get(ENV, "CI_COMMIT_REF_NAME", "") + pull_request = get(ENV, "CI_MERGE_REQUEST_ID", "false") + repo_slug = get(ENV, "CI_PROJECT_PATH", "") + tag = get(ENV, "CI_COMMIT_TAG", "") + event_type = get(ENV, "CI_PIPELINE_SOURCE", "") + + ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) + + returnfinaldeploy && begin ret = (ret..., uploader = uploader == GITLAB_CI) end + + elseif haskey(ENV, "DRONE") + + @info "Drone CI detected" + + cibranch = get(ENV, "DRONE_COMMIT_BRANCH", "") + pull_request = get(ENV, "DRONE_PULL_REQUEST", "false") + repo_slug = get(ENV, "DRONE_REPO_NAMESPACE", "") * "/" * get(ENV, "DRONE_REPO_NAME", "") + tag = get(ENV, "DRONE_TAG", "") + event_type = get(ENV, "DRONE_BUILD_EVENT", "") + + ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) + + returnfinaldeploy && begin ret = (ret..., uploader = uploader == DRONE) end + + elseif haskey(ENV, "CIRRUS_CI") + + @info "Cirrus CI detected" + + cibranch = get(ENV, "CIRRUS_BRANCH", "") + pull_request = get(ENV, "CIRRUS_PR", "false") + repo_slug = get(ENV, "CIRRUS_REPO_FULL_NAME", "") + tag = get(ENV, "CIRRUS_TAG", "") + event_type = "unknown" # Cirrus CI doesn't seem to provide the triggering event... + + ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) + + returnfinaldeploy && begin ret[6] = uploader == CIRRUS_CI end + + elseif haskey(ENV, "APPVEYOR") # the worst of them all + + @info "AppVeyor CI detected" + + pull_request = get(ENV, "APPVEYOR_PULL_REQUEST_NUMBER", "false") + cibranch = if haskey(ENV, "APPVEYOR_PULL_REQUEST_NUMBER" ) + ENV["APPVEYOR_PULL_REQUEST_HEAD_REPO_BRANCH"] + else + get(ENV, "APPVEYOR_REPO_BRANCH", "") + end + repo_slug = get(ENV, "APPVEYOR_PROJECT_SLUG", "") + tag = get(ENV, "APPVEYOR_REPO_TAG_NAME", "") + event_type = "unknown" # Appveyor has four env vars for this... + + ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) + + returnfinaldeploy && begin ret = (ret..., uploader = uploader == APPVEYOR) end + + else + @warn """ + We don't recognize the CI service you're running, or haven't added support for it. + We currently support Travis CI, Gitlab CI, Drone CI, Cirrus CI and AppVeyor. + """ + ret = (cibranch = nothing, pull_request = nothing, repo_slug = nothing, tag = nothing, event_type = nothing) + returnfinaldeploy && begin ret = (ret..., uploader = uploader == nothing) end + + end +end diff --git a/src/Documenter.jl b/src/Documenter.jl index 1b4b115d1e..dfb78f6286 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -36,6 +36,7 @@ abstract type Writer end # Submodules # ---------- +include("CISystems.jl") include("Utilities/Utilities.jl") include("DocMeta.jl") include("DocSystem.jl") @@ -373,144 +374,6 @@ makedocs( hide(root::Pair, children) = (true, root.first, root.second, map(hide, children)) hide(root::AbstractString, children) = (true, nothing, root, map(hide, children)) -""" - enum CI_SYSTEM - -The supported CI systems to deploy docs from, using Documenter.jl. - -Values: -* [`TRAVIS`](@ref) -* [`GITLAB_CI`](@ref) -* [`CIRRUS_CI`](@ref) -* [`DRONE`](@ref) -* [`APPVEYOR`](@ref) -""" -@enum CI_SYSTEM begin - TRAVIS - GITLAB_CI - CIRRUS_CI - DRONE - APPVEYOR -end -# docstrings for CI_SYSTEM values -"Specialize [`deploydocs`](@ref) for [Travis CI](https://travis-ci.org/). See also [`Documenter.CI_SYSTEM`](@ref)." -TRAVIS -"Specialize [`deploydocs`](@ref) for [Appveyor](https://www.appveyor.com/). See also [`Documenter.CI_SYSTEM`](@ref)." -APPVEYOR -"Specialize [`deploydocs`](@ref) for [GitLab CI](https://about.gitlab.com/product/continuous-integration/). See also [`Documenter.CI_SYSTEM`](@ref)." -GITLAB_CI -"Specialize [`deploydocs`](@ref) for [Cirrus CI](https://cirrus-ci.org/). See also [`Documenter.CI_SYSTEM`](@ref)." -CIRRUS_CI -"Specialize [`deploydocs`](@ref) for [Drone](https://drone.io/). See also [`Documenter.CI_SYSTEM`](@ref)." -DRONE - -""" - read_ci_env([returnfinaldeploy::Bool]; uploader::CI_SYSTEM = TRAVIS) - -Read the CI environment variables, and return (always) a NamedTuple where the first -five elements are, in order: - - `cibranch`: which branch is CI running on? - - `pull_request`: is CI building a pull request? Empty string if not. - - `repo_slug`: The URL-friendly repo name. - - `tag`: The tag being built bu CI. Empty string if not. - - `event_type`: The event that triggered CI. -Furthermore, if `returnfinaldeploy` is true, the function will check whether the -current CI provider matches `uploader` (set by default to Travis). - -Returns a NamedTuple. -""" -function read_ci_env(returnfinaldeploy=false; uploader::CI_SYSTEM = TRAVIS) - - arraylength = returnfinaldeploy ? 6 : 5 - - ret = nothing - - if haskey(ENV, "TRAVIS") - - @info "Travis CI detected" - - cibranch = get(ENV, "TRAVIS_BRANCH", "") - pull_request = get(ENV, "TRAVIS_PULL_REQUEST", "") - repo_slug = get(ENV, "TRAVIS_REPO_SLUG", "") - tag = get(ENV, "TRAVIS_TAG", "") - event_type = get(ENV, "TRAVIS_EVENT_TYPE", "") - - ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) - - returnfinaldeploy && begin ret = (ret..., uploader = uploader == TRAVIS) end - - elseif haskey(ENV, "GITLAB_CI") - - @info "Gitlab CI detected" - - cibranch = get(ENV, "CI_COMMIT_REF_NAME", "") - pull_request = get(ENV, "CI_MERGE_REQUEST_ID", "false") - repo_slug = get(ENV, "CI_PROJECT_PATH", "") - tag = get(ENV, "CI_COMMIT_TAG", "") - event_type = get(ENV, "CI_PIPELINE_SOURCE", "") - - ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) - - returnfinaldeploy && begin ret = (ret..., uploader = uploader == GITLAB_CI) end - - elseif haskey(ENV, "DRONE") - - @info "Drone CI detected" - - cibranch = get(ENV, "DRONE_COMMIT_BRANCH", "") - pull_request = get(ENV, "DRONE_PULL_REQUEST", "false") - repo_slug = get(ENV, "DRONE_REPO_NAMESPACE", "") * "/" * get(ENV, "DRONE_REPO_NAME", "") - tag = get(ENV, "DRONE_TAG", "") - event_type = get(ENV, "DRONE_BUILD_EVENT", "") - - ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) - - returnfinaldeploy && begin ret = (ret..., uploader = uploader == DRONE) end - - elseif haskey(ENV, "CIRRUS_CI") - - @info "Cirrus CI detected" - - cibranch = get(ENV, "CIRRUS_BRANCH", "") - pull_request = get(ENV, "CIRRUS_PR", "false") - repo_slug = get(ENV, "CIRRUS_REPO_FULL_NAME", "") - tag = get(ENV, "CIRRUS_TAG", "") - event_type = "unknown" # Cirrus CI doesn't seem to provide the triggering event... - - ret[1:5] .= (cibranch, pull_request, repo_slug, tag, event_type) - - returnfinaldeploy && begin ret[6] = uploader == CIRRUS_CI end - - elseif haskey(ENV, "APPVEYOR") # the worst of them all - - @info "AppVeyor CI detected" - - pull_request = get(ENV, "APPVEYOR_PULL_REQUEST_NUMBER", "false") - cibranch = if haskey(ENV, "APPVEYOR_PULL_REQUEST_NUMBER" ) - ENV["APPVEYOR_PULL_REQUEST_HEAD_REPO_BRANCH"] - else - get(ENV, "APPVEYOR_REPO_BRANCH", "") - end - repo_slug = get(ENV, "APPVEYOR_PROJECT_SLUG", "") - tag = get(ENV, "APPVEYOR_REPO_TAG_NAME", "") - event_type = "unknown" # Appveyor has four env vars for this... - - ret = (cibranch = cibranch, pull_request = pull_request, repo_slug = repo_slug, tag = tag, event_type = event_type) - - returnfinaldeploy && begin ret = (ret..., uploader = uploader == APPVEYOR) end - - else - @warn """ - We don't recognize the CI service you're running, or haven't added support for it. - We currently support Travis CI, Gitlab CI, Drone CI, Cirrus CI and AppVeyor. - """ - ret = (cibranch = nothing, pull_request = nothing, repo_slug = nothing, tag = nothing, event_type = nothing) - returnfinaldeploy && begin ret = (ret..., uploader = uploader == nothing) end - - end -end - - """ deploydocs( root = "", From d623f78a7e67307b1869b3c028299a1c3df8124c Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 28 Jul 2019 09:55:10 +0530 Subject: [PATCH 25/25] fix small bug --- src/Documenter.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index dfb78f6286..fdd1f9388d 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -616,7 +616,7 @@ function deploydocs(; Deployment criteria: - $(marker(repo_ok)) CI repo slug = "$(repo_slug)" occurs in repo = "$(repo)" - $(marker(pr_ok)) CI pull request indicator = "$(pull_request)" is "false" or "False" - - $(marker(tag_ok)) CI tag indicator = "$(localtag)" is (i) empty or (ii) a valid VersionNumber + - $(marker(tag_ok)) CI tag indicator = "$(tag)" is (i) empty or (ii) a valid VersionNumber - $(marker(branch_ok)) CI branch = "$(cibranch)" matches devbranch="$(devbranch)" (if tag is empty) - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists - $(marker(type_ok)) CI event type = "$(event_type)" is not "cron"