From c67017c8cf583400bf5d39536daf3f6cc1b294ba Mon Sep 17 00:00:00 2001 From: Chris de Graaf Date: Wed, 24 Jun 2020 16:32:43 -0500 Subject: [PATCH] Set up docs --- .github/workflows/TagBot.yml | 1 + .github/workflows/ci.yml | 18 ++++++ .gitignore | 1 + README.md | 14 +++++ docs/Project.toml | 3 + docs/make.jl | 21 +++++++ docs/src/index.md | 12 ++++ src/GitHubActions.jl | 105 ++++++++++++++++++++++++++++++++++- 8 files changed, 173 insertions(+), 2 deletions(-) create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/index.md diff --git a/.github/workflows/TagBot.yml b/.github/workflows/TagBot.yml index dd911f3..d885279 100644 --- a/.github/workflows/TagBot.yml +++ b/.github/workflows/TagBot.yml @@ -9,3 +9,4 @@ jobs: - uses: JuliaRegistries/TagBot@v1 with: token: ${{ secrets.GITHUB_TOKEN }} + ssh: ${{ secrets.DOCUMENTER_KEY }} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5b39dee..77124ba 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,3 +34,21 @@ jobs: ${{ runner.os }}- - uses: julia-actions/julia-buildpkg@latest - uses: julia-actions/julia-runtest@latest + continue-on-error: ${{ matrix.version == 'nightly' }} + docs: + name: Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: julia-actions/setup-julia@v1 + with: + version: '1' + - run: | + julia --project=docs -e ' + using Pkg + Pkg.develop(PackageSpec(path=pwd())) + Pkg.instantiate()' + - run: julia --project=docs docs/make.jl + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} diff --git a/.gitignore b/.gitignore index ba39cc5..11b69ed 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ +/docs/build/ Manifest.toml diff --git a/README.md b/README.md index 993fe61..c3d5176 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,17 @@ # GitHubActions +[![Docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://julia-actions.github.io/GitHubActions.jl) [![Build Status](https://github.com/julia-actions/GitHubActions.jl/workflows/CI/badge.svg)](https://github.com/julia-actions/GitHubActions.jl/actions) + +Utilities for working within GitHub Actions, modelled after [`actions/core`](https://github.com/actions/toolkit/tree/master/packages/core). + +Perhaps the most common use case is to set the global logger to one compatible with GitHub Actions' log format: + +```jl +using Logging: global_logger +using GitHubActions: GitHubActionsLogger +get(ENV, "GITHUB_ACTIONS", "false") == "true" && global_logger(GitHubActionsLogger()) +@warn "This warning will be visible in your GitHub Actions logs!" +``` + +For information on the other provided functions, see the documentation. diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..6fb5fd5 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,3 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +GitHubActions = "6b79fd1a-b13a-48ab-b6b0-aaee1fee41df" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..1fb53e0 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,21 @@ +using GitHubActions +using Documenter + +makedocs(; + modules=[GitHubActions], + authors="Chris de Graaf and contributors", + repo="https://github.com/julia-actions/GitHubActions.jl.jl/blob/{commit}{path}#L{line}", + sitename="GitHubActions.jl", + format=Documenter.HTML(; + prettyurls=get(ENV, "CI", "false") == "true", + canonical="https://julia-actions.github.io/GitHubActions.jl", + assets=String[], + ), + pages=[ + "Home" => "index.md", + ], +) + +deploydocs(; + repo="github.com/julia-actions/GitHubActions.jl", +) diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..6484d2b --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,12 @@ +```@meta +CurrentModule = GitHubActions +``` + +# GitHubActions + +```@index +``` + +```@autodocs +Modules = [GitHubActions] +``` diff --git a/src/GitHubActions.jl b/src/GitHubActions.jl index 0eb3f52..aded4b0 100644 --- a/src/GitHubActions.jl +++ b/src/GitHubActions.jl @@ -24,6 +24,12 @@ using JSON: json const CMD_MARKER = "::" +""" + MissingInputError(k) + +Indicates that a required input was not provided. +The input's name is stored in `k`. +""" struct MissingInputError <: Exception k::String end @@ -63,46 +69,141 @@ function command(cmd, props, val) println(s) end +fail() = exit(1) + +""" + end_group() + +End a group that was started with [`start_group`](@ref). +""" end_group() = command("endgroup", (), "") + +""" + get_state(k) + +Get the state variable with name `k`. +""" get_state(k) = get(ENV, "STATE_$k", "") + +""" + log_debug(msg) + +Log a debug message. +See also [`GitHubActionsLogger`](@ref). +""" log_debug(msg) = command("debug", (), msg) + +""" + log_error(msg) + +Log an error message. +See also [`GitHubActionsLogger`](@ref). +""" log_error(msg) = command("error", (), msg) + +""" + log_warning(msg) + +Log a warning message. +See also [`GitHubActionsLogger`](@ref). +""" log_warning(msg) = command("warning", (), msg) + +""" + save_state(k, v) + +Save value `v` with name `k` to state. +""" save_state(k, v) = command("save-state", (name=k,), v) + +""" + set_command_echo(enable) + +Enable or disable command echoing. +""" set_command_echo(enable) = command("echo", (), enable ? "on" : "off") + +""" + set_output(k, v) + +Set the output with name `k` to value `v`. +""" set_output(k, v) = command("set-output", (name=k,), v) -set_secret(k) = command("add-mask", (), k) + +""" + set_secret(v) + +Mask the value `v` in logs. +""" +set_secret(v) = command("add-mask", (), v) + +""" + start_group(name) + +Start a foldable group called `name`. +""" start_group(name) = command("group", (), name) +""" + add_path(v) + +Add `v` to the system `PATH`. +""" function add_path(v) sep = @static Sys.iswindows() ? ';' : ':' ENV["PATH"] = v * sep * ENV["PATH"] command("add-path", (), v) end +""" + get_input(k; required=false) + +Get an input. +If `required` is set and the input is not, a [`MissingInputError`](@ref) is thrown. +""" function get_input(k; required=false) val = get(ENV, "INPUT_" * uppercase(replace(k, ' ' => '_')), "") required && isempty(val) && throw(MissingInputError(k)) return string(strip(val)) end +""" + group(f, name) + +Run `f` inside of a foldable group. +See also [`start_group`](@ref) and [`end_group`](@ref). +""" function group(f, name) start_group(name) return try f() finally end_group() end end +""" + set_env(k, v) + +Set environment variable `k` to value `v`. +""" function set_env(k, v) val = cmd_value(v) ENV[k] = val command("set-env", (name=k,), val) end -fail() = exit(1) +""" + set_failed(msg) + +Error with `msg`, and set the process exit code to `1`. +""" function set_failed(msg) atexit(fail) log_error(msg) end +""" + GitHubActionsLogger() + +A logger that prints to standard output in the format expected by GitHub Actions. +""" struct GitHubActionsLogger <: AbstractLogger end Logging.catch_exceptions(::GitHubActionsLogger) = true