Add DeployConfig for GitHub Actions.

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 * ![Feature][badge-feature] Deployment is now more customizable and thus not as tied to Travis CI as before. ([#1147][github-1147])
 
+* ![Feature][badge-feature] Documenter now has builtin support for deploying from GitHub Actions. ([#1144][github-1144])
+
 * ![Enhancement][badge-enhancement] In the PDF/LaTeX output, images that are wider than the text are now being scaled down to text width automatically. The PDF builds now require the [adjustbox](https://ctan.org/pkg/adjustbox) LaTeX package to be available. ([#1137][github-1137])
 
 ## Version `v0.23.3`
@@ -414,6 +416,7 @@
 [github-1082]: https://github.com/JuliaDocs/Documenter.jl/pull/1082
 [github-1115]: https://github.com/JuliaDocs/Documenter.jl/pull/1115
 [github-1137]: https://github.com/JuliaDocs/Documenter.jl/pull/1137
+[github-1144]: https://github.com/JuliaDocs/Documenter.jl/pull/1144
 [github-1147]: https://github.com/JuliaDocs/Documenter.jl/pull/1147
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl

docs/src/man/hosting.md

@@ -2,8 +2,9 @@
 
 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
-and GitHub Pages. This is the same approach used by this package to host its own docs --
+describe how to setup automatic updates for your package docs using either the Travis CI
+build service or GitHub Actions together with and GitHub Pages for hosting the generated
+HTML files. This is the same approach used by this package to host its own docs --
 the docs you're currently reading.
 
 !!! note
@@ -17,16 +18,16 @@ the docs you're currently reading.
     [Travis](https://travis-ci.com/) accounts setup. If not then go set those up first and
     then return here.
 
-    In this guide we use Travis CI for deployment, but it is possible to customize
-    Documenter such that other services can be used, see [Deployment systems](@ref).
+    It is possible to deploy from other systems than Travis CI or GitHub Actions,
+    see the section on [Deployment systems](@ref).
 
 
 ## Overview
 
 Once set up correctly, the following will happen each time you push new updates to your
 package repository:
 
-- Travis buildbots will start up and run your package tests in a "Test" stage.
+- Buildbots will start up and run your package tests in a "Test" stage.
 - After the Test stage completes, a single bot will run a new "Documentation" stage, which
   will build the documentation.
 - If the documentation is built successfully, the bot will attempt to push the generated
@@ -41,7 +42,7 @@ The following sections outline how to enable this for your own package.
 ## SSH Deploy Keys
 
 Deploy keys provide push access to a *single* repository, to allow secure deployment of
-generated documentation from Travis to GitHub. The SSH keys can be generated with the
+generated documentation from the builder to GitHub. The SSH keys can be generated with the
 `Travis.genkeys` from the [DocumenterTools](https://github.com/JuliaDocs/DocumenterTools.jl)
 package.
 
@@ -119,7 +120,15 @@ Follow the instructions that are printed out, namely:
     There are more explicit instructions for adding the keys to GitHub and Travis in the
     [SSH Deploy Keys Walkthrough](@ref) section of the manual.
 
-## `.travis.yml` Configuration
+## Configuration files for the builder
+
+In the upcoming sections we describe how to configure the build service to run
+the documentation build stage. In general it is easiest to choose the same
+service as the one testing your package. If you don't explicitly select
+the service with the `deploy_config` keyword argument to `deploydocs`
+Documenter will try to automatically detect which system is running and use that.
+
+### Travis CI: `.travis.yml`
 
 To tell Travis that we want a new build stage we can add the following to the `.travis.yml`
 file:
@@ -153,6 +162,52 @@ The three lines in the `script:` section do the following:
     `Pkg.build("PackageName")` after the call to `Pkg.develop` to make
     sure the package is built properly.
 
+
+### GitHub Actions
+
+To run the documentation build from GitHub Actions you should add the following to your
+workflow configuration file:
+
+```yaml
+name: Documentation
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        julia-version: [1.2.0]
+        julia-arch: [x86]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v1.0.0
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: ${{ matrix.julia-version }}
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+        run: julia --project=docs/ docs/make.jl
+```
+
+which will install Julia, checkout the correct commit of your repository, and run the
+build of the documentation.
+
+where the `julia-version:`, `julia-arch:` and `os:` entries decide the worker from which
+the docs are built and deployed. In the example above we will thus build and deploy the
+documentation from a ubuntu worker running Julia 1.2. For more information on how to setup
+a GitHub workflow see the manual for
+[Configuring a workflow](https://help.github.com/en/articles/configuring-a-workflow).
+
+The commands in the lines in the `run:` section do the same as for Travis,
+see the previous section.
+
+## `docs/Project.toml`
+
 The doc-build environment `docs/Project.toml` includes Documenter and other doc-build
 dependencies your package might have. If Documenter is the only dependency, then the
 `Project.toml` should include the following:
@@ -287,16 +342,17 @@ look at this package's repository for some inspiration.
 
 ## Deployment systems
 
-In the guide above we used Travis CI for building and pushing updates to the documentation.
-However, it is possible to customize Documenter to use other systems. This is done by
-passing a configuration (a [`DeployConfig`](@ref Documenter.DeployConfig)) to `deploydocs`
-by the `deploy_config` keyword argument. Currently, only [`Travis`](@ref) is implemented,
-but it is easy to define your own by following the simple interface described below.
+It is possible to customize Documenter to use other systems then the ones described in
+the sections above. This is done by passing a configuration
+(a [`DeployConfig`](@ref Documenter.DeployConfig)) to `deploydocs` by the `deploy_config`
+keyword argument. Currently, only [`Travis`](@ref) is implemented, but it is easy to define
+your own by following the simple interface described below.
 
 ```@docs
 Documenter.DeployConfig
 Documenter.documenter_key
 Documenter.git_tag
 Documenter.should_deploy
 Documenter.Travis
+Documenter.GitHubActions
 ```

src/deployconfig.jl

@@ -48,6 +48,8 @@ The following environment variables influences the build
 when using the `Travis` configuration:
 
  - `DOCUMENTER_KEY`: must contain the Base64-encoded SSH private key for the repository.
+   This variable should be set in the Travis settings for the repository. Make sure this
+   variable is marked **NOT** to be displayed in the build log.
 
  - `TRAVIS_PULL_REQUEST`: must be set to `false`.
    This avoids deployment on pull request builds.
@@ -67,9 +69,8 @@ when using the `Travis` configuration:
    a package version tag gets deployed to a directory named after the version number in
    `TRAVIS_TAG` instead.
 
-The `TRAVIS_*` variables are set automatically on Travis, but could be set manually to
-appropriate values as well. More information on how Travis sets the `TRAVIS_*` variables
-can be found in the
+The `TRAVIS_*` variables are set automatically on Travis. 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).
 """
 struct Travis <: DeployConfig
@@ -121,3 +122,78 @@ end
 function git_tag(cfg::Travis)
     isempty(cfg.travis_tag) ? nothing : cfg.travis_tag
 end
+
+
+##################
+# GitHub Actions #
+##################
+
+"""
+    GitHubActions <: DeployConfig
+
+Implementation of `DeployConfig` for deploying from GitHub Actions.
+
+The following environment variables influences the build
+when using the `GitHubActions` configuration:
+
+ - `DOCUMENTER_KEY`: must contain the Base64-encoded SSH private key for the repository.
+   This variable should be set in the GitHub Actions configuration file using a repository
+   secret, see the documentation for
+   [secret environment variables](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables).
+
+ - `GITHUB_EVENT_NAME`: must be set to `push`.
+   This avoids deployment on pull request builds.
+
+ - `GITHUB_REPOSITORY`: must match the value of the `repo` keyword to [`deploydocs`](@ref).
+
+ - `GITHUB_REF`: must match the `devbranch` keyword to [`deploydocs`](@ref), alternatively
+   correspond to a git tag.
+
+The `GITHUB_*` variables are set automatically on GitHub Actions, see the
+[documentation](https://help.github.com/en/articles/virtual-environments-for-github-actions#default-environment-variables).
+"""
+struct GitHubActions <: DeployConfig
+    github_repository::String
+    github_event_name::String
+    github_ref::String
+end
+function GitHubActions()
+    github_repository = get(ENV, "GITHUB_REPOSITORY", "") # "JuliaDocs/Documenter.jl"
+    github_event_name = get(ENV, "GITHUB_EVENT_NAME", "") # "push", "pull_request" or "cron" (?)
+    github_ref        = get(ENV, "GITHUB_REF",        "") # "refs/heads/$(branchname)" for branch, "refs/tags/$(tagname)" for tags
+    return GitHubActions(github_repository, github_event_name, github_ref)
+end
+
+# Check criteria for deployment
+function should_deploy(cfg::GitHubActions; repo, devbranch, kwargs...)
+    ## The deploydocs' repo should match GITHUB_REPOSITORY
+    repo_ok = occursin(cfg.github_repository, repo)
+    ## Do not deploy for PRs
+    pr_ok = cfg.github_event_name == "push"
+    ## If a tag exist it should be a valid VersionNumber
+    m = match(r"^refs/tags/(.*)$", cfg.github_ref)
+    tag_ok = m === nothing ? false : occursin(Base.VERSION_REGEX, String(m.captures[1]))
+    ## If no tag exists deploydocs' devbranch should match the current branch
+    m = match(r"^refs/heads/(.*)$", cfg.github_ref)
+    branch_ok = m === nothing ? false : String(m.captures[1]) == devbranch
+    ## DOCUMENTER_KEY should exist (just check here and extract the value later)
+    key_ok = haskey(ENV, "DOCUMENTER_KEY")
+    # ## Cron jobs should not deploy
+    # type_ok = cfg.travis_event_type != "cron"
+    all_ok = repo_ok && pr_ok && (tag_ok || branch_ok) && key_ok # && type_ok
+    marker(x) = x ? "✔" : "✘"
+    @info """Deployment criteria for deploying with GitHub Actions:
+    - $(marker(repo_ok)) ENV["GITHUB_REPOSITORY"]="$(cfg.github_repository)" occurs in repo="$(repo)"
+    - $(marker(pr_ok)) ENV["GITHUB_EVENT_NAME"]="$(cfg.github_event_name)" is "push"
+    - $(marker(tag_ok || branch_ok)) ENV["GITHUB_REF"]="$(cfg.github_ref)" corresponds to a tag or matches devbranch="$(devbranch)"
+    - $(marker(key_ok)) ENV["DOCUMENTER_KEY"] exists
+    Deploying: $(marker(all_ok))
+    """
+    return all_ok
+end
+
+# Obtain git tag for the build
+function git_tag(cfg::GitHubActions)
+    m = match(r"^refs/tags/(.*)$", cfg.github_ref)
+    return m === nothing ? nothing : String(m.captures[1])
+end