Set up docs

.github/workflows/TagBot.yml

@@ -9,3 +9,4 @@ jobs:
       - uses: JuliaRegistries/TagBot@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.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 }}

.gitignore

@@ -1 +1,2 @@
+/docs/build/
 Manifest.toml

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.

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+GitHubActions = "6b79fd1a-b13a-48ab-b6b0-aaee1fee41df"

docs/make.jl

@@ -0,0 +1,21 @@
+using GitHubActions
+using Documenter
+
+makedocs(;
+    modules=[GitHubActions],
+    authors="Chris de Graaf <me@cdg.dev> 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",
+)

docs/src/index.md

@@ -0,0 +1,12 @@
+```@meta
+CurrentModule = GitHubActions
+```
+
+# GitHubActions
+
+```@index
+```
+
+```@autodocs
+Modules = [GitHubActions]
+```

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