Initial implementation (#1)

* First pass at generating and deploying jazzy docs to github pages

Author: Steven0351

.gitignore

@@ -33,7 +33,6 @@ bower_components
 build/Release
 
 # Dependency directories
-node_modules/
 jspm_packages/
 
 # TypeScript v1 declaration files

README.md

@@ -0,0 +1,79 @@
+# Publish Jazzy Docs to Github Pages
+This is a GitHub Action generate and publish [Jazzy](https://github.com/realm/jazzy/) documentation for your Swift and/or Objective-C projects.
+
+## Assumptions
+This Action expects the following to be true:
+* Your workflow runs on macOS
+* You have documentation comments present in your Swift/Objective-C project (otherwise you will be generating a pretty useless website)
+* You have a `gh-pages` branch in your repository
+* A personal access token with `repo` scope. The `GITHUB_TOKEN` available as part of an action will not trigger a Github Pages build. See [this discussion thread](https://github.community/t5/GitHub-Actions/Github-action-not-triggering-gh-pages-upon-push/td-p/26869) for more information.
+
+## Configuration
+|Key|Description|Required|
+|---|---|:---:|
+| `personal_access_token` | A personal access token with repo scope for pushing documentation to `gh-pages` branch. See [Creating a Personal Access Token](https://help.github.com/en/enterprise/2.17/user/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) for creating the token and [Creating and Using Secrets](https://help.github.com/en/github/automating-your-workflow-with-github-actions/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables) for including secrets to be used in tandem with Github Actions. | Yes |
+| `config` | The path to a Jazzy yaml configuration file| No |
+| `args` | Command line arguments to be passed to Jazzy. See `jazzy --help` on your local machine for available options| No |
+| `version` | The Jazzy version to run. Defaults to latest | No
+
+## Limitations
+This Action will never support the following:
+* Generating and deploying documentation to `master` or in a docs folder on `master`
+* Maintain commit history of the `gh-pages` branch.
+
+This Action does not currently support the following:
+* .json configuration files
+* Specifying both `config` and `args`. Any `args` provided along with `config` will be ignored.
+
+## Usage
+Documentation generation can be as minimal as the following:
+```yaml
+name: PublishDocumentation
+
+on: 
+  release:
+    types: [published]
+
+jobs:
+  deploy_docs:
+    runs-on: macOS-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Publish Jazzy Docs
+      uses: steven0351/publish-jazzy-docs@v1
+      with:
+        personal_access_token: ${{ secrets.ACCESS_TOKEN }}
+```
+
+Specify a Jazzy config file:
+```yaml
+...
+    - name: Publish Jazzy Docs
+      uses: steven0351/publish-jazzy-docs@v1
+      with:
+        personal_access_token: ${{ secrets.ACCESS_TOKEN }}
+        config: .jazzy.yml
+```
+
+Pass CLI args:
+```yaml
+...
+    - name: Publish Jazzy Docs
+      uses: steven0351/publish-jazzy-docs@v1
+      with:
+        personal_access_token: ${{ secrets.ACCESS_TOKEN }}
+        args: "--theme fullwidth --author Johnny Appleseed"
+```
+
+Specify a Jazzy version:
+```yaml
+...
+    - name: Publish Jazzy Docs
+      uses: steven0351/publish-jazzy-docs@v1
+      with:
+        personal_access_token: ${{ secrets.ACCESS_TOKEN }}
+        version: 0.11.2
+```
+
+## Contributions
+Pull requests are the preferred method of contributing. If you are unable to create a pull request, a detailed GitHub Issue describing the bug or feature request is more than welcome.

action.yml

@@ -0,0 +1,18 @@
+name: "Publish Jazzy Docs:"
+desc: "Generate Swift/Obj-C documentation with Jazzy and publish to Github Pages"
+inputs:
+  config:
+    description: "Path to .jazzy.yml file - preferred"
+    required: false
+  args:
+    description: "Arguments to pass to Jazzy"
+    required: false
+  version:
+    description: "Jazzy Version"
+    required: false
+  personal_access_token:
+    description: "Personal access token"
+    required: true
+runs:
+  using: "node12"
+  main: "main.js"

main.js

@@ -0,0 +1,95 @@
+const core = require("@actions/core")
+const github = require("@actions/github")
+const shell = require("shelljs")
+const yaml = require("js-yaml")
+const fs = require("fs")
+
+const context = github.context
+
+const branch = "gh-pages"
+
+// User defined input
+const jazzyVersion = core.getInput("version")
+const configFilePath = core.getInput("config")
+const jazzyArgs = core.getInput("args")
+const token = core.getInput("personal_access_token")
+
+const remote = `https://${token}@github.com/${context.repo.owner}/${context.repo.repo}.git`
+
+const generateJazzyInstallCommand = () => {
+  let gemInstall = "sudo gem install jazzy"
+
+  if (jazzyVersion) {
+    gemInstall + ` -v ${jazzyVersion}`
+  }
+
+  return gemInstall
+}
+
+const generateJazzyArguments = () => {
+  if (configFilePath) {
+    return `jazzy --config ${configFilePath}`
+  }
+
+  if (jazzyArgs) {
+    return `jazzy ${jazzyArgs}`
+  }
+
+  return "jazzy"
+}
+
+const sliceDocumentsFromJazzyArgs = (outputArg) => {
+  const startIndexOfDocsDir = jazzyArgs.indexOf(outputArg) + outputArg.length + 1
+  const endIndexOfDocsDir = jazzyArgs.indexOf(" ", startIndexOfDocsDir)
+
+  if (endIndexOfDocsDir != -1) {
+    return jazzyArgs.slice(startIndexOfDocsDir, endIndexOfDocsDir)
+  } else {
+    return jazzyArgs.slice(startIndexOfDocsDir)
+  }
+}
+
+const getDocumentationFolder = () => {
+  if (configFilePath) {
+    const config = yaml.safeLoad(fs.readFileSync(configFilePath, "utf8"))
+    if (config.output) {
+      return config.output
+    }
+  }
+
+  if (jazzyArgs) {
+    // --output needs to be checked first, because --output includes -o
+    if (jazzyArgs.includes("--output")) {
+      return sliceDocumentsFromJazzyArgs("--output")
+    }
+
+    if (jazzyArgs.includes("-o")) {
+      return sliceDocumentsFromJazzyArgs("-o")
+    }
+  }
+
+  return "docs"
+}
+
+const generateAndDeploy = () => {
+  shell.exec(generateJazzyInstallCommand())
+  shell.exec(generateJazzyArguments())
+  shell.cp("-r", `${getDocumentationFolder()}/*`, "../")
+
+  shell.cd("../")
+  shell.rm("-rf", `${process.env.GITHUB_WORKSPACE}`)
+
+  shell.exec("git init")
+  shell.exec(`git config user.name ${context.actor}`)
+  shell.exec(`git config user.email ${context.actor}@users.noreply.github.com`)
+  shell.exec("git add .")
+  shell.exec("git commit -m 'Deploying Updated Jazzy Docs'")
+  shell.exec(`git push --force ${remote} master:${branch}`)
+}
+
+try {
+  generateAndDeploy()
+} catch (error) {
+  core.setFailed(error.message)
+}
+