Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Check env vars for non-Travis CI platforms #1067

Closed
wants to merge 29 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
42af534
First pass at decoupling manual deploy from generic CI
asinghvi17 Jan 1, 2019
1cb28eb
Check env vars for non-Travis CI platforms
asinghvi17 Jul 13, 2019
7467920
implement preferred uploader
asinghvi17 Jul 13, 2019
2986dab
Better pull request check message
asinghvi17 Jul 14, 2019
b970a99
Make LaTeXWriter check for tag on all CIs
asinghvi17 Jul 14, 2019
e48fafa
Create and export a CI_SYSTEM enum
asinghvi17 Jul 14, 2019
3bef32b
Document and add CHANGELOG
asinghvi17 Jul 14, 2019
2175bb1
fix overlapping variable names
asinghvi17 Jul 14, 2019
b3b409b
Merge branch 'master' into as/generic-ci
asinghvi17 Jul 14, 2019
06422a8
Add PR nr, don't have it experimental
mortenpi Jul 14, 2019
b4c7620
Remove exp badge, add untested info
asinghvi17 Jul 15, 2019
1ef6c5c
read CI env in fcn, better manual deploy
asinghvi17 Jul 15, 2019
17acc66
FIX TYPE
asinghvi17 Jul 15, 2019
0dea970
Apply suggestions from review
asinghvi17 Jul 16, 2019
26c5aff
Add functions to docs (wow that was easy)
asinghvi17 Jul 16, 2019
edbf343
Fix misuse of tag
asinghvi17 Jul 16, 2019
4ee8b8f
Fix bad link
mortenpi Jul 17, 2019
cd753ed
Add CHANGELOG for tag change
mortenpi Jul 17, 2019
f58f06f
Add docs
mortenpi Jul 17, 2019
07bca34
warning doesn't exist + code style
mortenpi Jul 17, 2019
588fc01
Change to namedtuple return type
asinghvi17 Jul 23, 2019
e550502
Remove manual tag setting from changelog
asinghvi17 Jul 23, 2019
844d1f4
Remove empty line in CHANGELOG.md
asinghvi17 Jul 23, 2019
61ecc09
Merge branch 'as/generic-ci' of https://github.com/asinghvi17/Documen…
asinghvi17 Jul 23, 2019
7a256b8
Merge branch 'master' into as/generic-ci
asinghvi17 Jul 23, 2019
51eb94f
Import `read_ci_env` to LaTeXWriter
asinghvi17 Jul 23, 2019
9d3f16e
Merge branch 'as/generic-ci' of https://github.com/asinghvi17/Documen…
asinghvi17 Jul 23, 2019
338d05d
Change structure so that LaTeXWriter can read CI variables
asinghvi17 Jul 25, 2019
d623f78
fix small bug
asinghvi17 Jul 28, 2019
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@

* ![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`. However, be aware that CI systems other than Travis CI have not received extensive testing. ([#1067][github-1067])

asinghvi17 marked this conversation as resolved.
Show resolved Hide resolved
* ![Enhancement][badge-enhancement] The PDF output now uses the DejaVu Sans and DejaVu Sans Mono fonts to provide better Unicode coverage. ([#803][github-803], [#1066][github-1066])

* ![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])
Expand Down Expand Up @@ -383,6 +386,7 @@
[github-1061]: https://github.com/JuliaDocs/Documenter.jl/pull/1061
[github-1062]: https://github.com/JuliaDocs/Documenter.jl/pull/1062
[github-1066]: https://github.com/JuliaDocs/Documenter.jl/pull/1066
[github-1067]: https://github.com/JuliaDocs/Documenter.jl/pull/1067
[github-1071]: https://github.com/JuliaDocs/Documenter.jl/pull/1071

[documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
Expand Down
1 change: 1 addition & 0 deletions docs/src/lib/internals/documenter.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,5 @@
```@docs
Documenter.gitrm_copy
Documenter.git_push
Documenter.read_ci_env
```
11 changes: 11 additions & 0 deletions docs/src/lib/public.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,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
Expand Down
13 changes: 10 additions & 3 deletions docs/src/man/hosting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
3 changes: 2 additions & 1 deletion docs/src/man/hosting/walkthrough.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,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

Expand Down
136 changes: 136 additions & 0 deletions src/CISystems.jl
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe, for a more cleaner API here, it would be better if read_ci_env would just return nothing if the CI env can not be detected? That way the call sites do not have to do the haskey(ENV, "CI") check, which may actually be different on different CI systems (in general). So instead, they would check if this returned nothing or not, and decide whether we're in CI based on that.

"""
function read_ci_env(returnfinaldeploy=false; uploader::CI_SYSTEM = TRAVIS)

arraylength = returnfinaldeploy ? 6 : 5
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unused


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not actually returning anything?

Loading