From 47fa78221cef983a352b80a83befc25a6283c83c Mon Sep 17 00:00:00 2001
From: Sascha Mann <git@mail.saschamann.eu>
Date: Sat, 26 Dec 2020 15:29:46 +0100
Subject: [PATCH] Improve docs (#57)

* Move versioninfo section and update ToC

* Add docs for in- and outputs to README

Inspired by actions/checkout docs
---
 README.md | 76 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 58 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 5e682a2..062bce3 100644
--- a/README.md
+++ b/README.md
@@ -7,18 +7,58 @@ This action sets up a Julia environment for use in actions by downloading a spec
 ## Table of Contents
 - [Table of Contents](#table-of-contents)
 - [Usage](#usage)
+  - [Inputs](#inputs)
+  - [Outputs](#outputs)
   - [Basic](#basic)
   - [Julia Versions](#julia-versions)
   - [Matrix Testing](#matrix-testing)
+  - [versioninfo](#versioninfo)
 - [Versioning](#versioning)
 - [Debug logs](#debug-logs)
 - [Third party information](#third-party-information)
 
 ## Usage
 
-See [action.yml](action.yml).
+### Inputs
 
-You can find a list of example workflows making use of this action here: [julia-actions/example-workflows](https://github.com/julia-actions/example-workflows).
+```yaml
+- uses: julia-actions/setup-julia@v1
+  with:
+    # The Julia version that will be installed and added as `julia` to the PATH.
+    # See "Julia Versions" below for a list of valid values.
+    #
+    # Warning: It is strongly recommended to wrap this value in quotes.
+    #          Otherwise, the YAML parser used by GitHub Actions parses certain
+    #          versions as numbers which causes the wrong version to be selected.
+    #          For example, `1.0` may be parsed as `1`.
+    #
+    # Default: '1'
+    version: ''
+
+    # The architecture of the Julia binaries.
+    #
+    # Supported values: x64 | x86
+    #
+    # Default: x64
+    arch: ''
+
+    # If true, display the output of InteractiveUtils.versioninfo() after installing.
+    # See "versioninfo" below for example usage.
+    #
+    # Default: false
+    show-versioninfo: ''
+```
+
+### Outputs
+
+```yaml
+outputs:
+  # Path to the directory containing the Julia executable.
+  # Equivalent to JULIA_BINDIR: https://docs.julialang.org/en/v1/manual/environment-variables/#JULIA_BINDIR
+  #
+  # Example output: '/opt/hostedtoolcache/julia/1.5.3/x64/bin'
+  julia-bindir: ''
+```
 
 ### Basic
 
@@ -35,7 +75,7 @@ steps:
 
 You can either specify specific Julia versions or version ranges. If you specify a version range, the **highest** available Julia version that matches the range will be selected.
 
-**Warning:** It is strongly recommended to wrap versions in quotes. Otherwise, the YAML parser used by GitHub Actions parses certain versions as numbers which causes the wrong version to be selected. For example, `1.0` is parsed as `1`.
+**Warning:** It is strongly recommended to wrap versions in quotes. Otherwise, the YAML parser used by GitHub Actions parses certain versions as numbers which causes the wrong version to be selected. For example, `1.0` may be parsed as `1`.
 
 #### Examples
 
@@ -129,6 +169,21 @@ jobs:
         shell: bash
 ```
 
+### versioninfo
+
+By default, only a brief version identifier is printed in the run log. You can display the full `versioninfo` by adding `show-versioninfo`.
+Here's an example that prints this information just for `nightly`:
+
+```yaml
+    - uses: julia-actions/setup-julia@v1
+      with:
+        version: ${{ matrix.version }}
+        arch: ${{ matrix.arch }}
+        show-versioninfo: ${{ matrix.version == 'nightly' }}
+ ```
+ 
+You use `'true'` if you want it printed for all Julia versions.
+
 ## Versioning
 
 This action follows [GitHub's advice](https://help.github.com/en/articles/about-actions#versioning-your-action) on versioning actions, with an additional `latest` tag.
@@ -152,21 +207,6 @@ If your workflow requires access to secrets, you should always pin it to a commi
 This will protect you in case a bad actor gains access to the setup-julia repo.
 You can find more information in [GitHub's security hardening guide](https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions).
 
-## versioninfo
-
-By default, only a brief version identifier is printed in the run log. You can display the full `versioninfo` by adding `show-versioninfo`.
-Here's an example that prints this information just for `nightly`:
-
-```yaml
-    - uses: julia-actions/setup-julia@v1
-      with:
-        version: ${{ matrix.version }}
-        arch: ${{ matrix.arch }}
-        show-versioninfo: ${{ matrix.version == 'nightly' }}
- ```
- 
-You use `'true'` if you want it printed for all Julia versions.
-
 ## Debug logs
 
 You can enable [Step Debug Logs](https://github.com/actions/toolkit/blob/main/docs/action-debugging.md#step-debug-logs) for more detailed logs.