Merge pull request #40 from playframework/antora

Reusable workflow for Antora

.github/workflows/antora.yml

@@ -0,0 +1,64 @@
+name: Generate documentation with Antora
+
+on:
+  workflow_call:
+    inputs:
+      path:
+        type: string
+        required: false
+        default: './'
+      playbook:
+        type: string
+        required: false
+        default: 'local-antora-playbook.yml'
+      publish:
+        type: boolean
+        required: false
+        default: false
+
+jobs:
+  docs:
+    name: Antora
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          # we don't know what commit the last tag was it's safer to get entire repo so previousStableVersion resolves
+          fetch-depth: 0
+
+      - name: Install NodeJS
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+
+      - name: Get npm cache directory
+        id: npm-cache-dir
+        run: |
+          echo "::set-output name=dir::$(npm config get cache)"
+      - uses: actions/cache@v3
+        id: npm-cache # use this to check for `cache-hit` ==> if: steps.npm-cache.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.npm-cache-dir.outputs.dir }}
+          key: ${{ runner.os }}-node-antora@3.1.1-lunr-extension@1.0.0-alpha.8
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install Antora and extensions
+        run: npm i -D -E --quiet --no-progress @antora/cli@3.1.1 @antora/site-generator@3.1.1 @antora/lunr-extension@1.0.0-alpha.8
+        working-directory: ${{ inputs.path }}
+
+      - name: Build documentation
+        run: npx antora ${{ inputs.playbook }}
+        working-directory: ${{ inputs.path }}
+
+      - name: Publish to GitHub Pages
+        if: ${{ inputs.publish }}
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ inputs.path }}/build/site
+          force_orphan: true
+          commit_message: "Deploy docs"
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'

README.md

@@ -21,6 +21,7 @@ This repository contains a few configurations of GitHub features. For example a
 * [Publishing to Sonatype](#publishing-to-sonatype)
 * [Validate Binary Compatibility](#validate-binary-compatibility)
 * [Mark Pull Request as Ready To Merge](#mark-pull-request-as-ready-to-merge)
+* [Generate documentation with Antora](#generate-documentation-with-antora)
 
 ### Universal CMD task
 
@@ -146,6 +147,33 @@ needs: # Should be latest
 uses: playframework/.github/.github/workflows/rtm.yml@v2
 ```
 
+### Generate documentation with Antora
+
+This workflow is used for generate and optionally publish documentation with [Antora](http://antora.org).
+
+**Path**: [`.github/workflows/antora.yml`](.github/workflows/antora.yml)
+
+**Image**: [Ubuntu 20.04](https://hub.docker.com/layers/ubuntu/library/ubuntu/20.04/images/sha256-57df66b9fc9ce2947e434b4aa02dbe16f6685e20db0c170917d4a1962a5fe6a9?context=explore)
+
+**Uses actions**:
+* [Setup Node](https://github.com/actions/setup-node)
+* [Cache](https://github.com/actions/cache)
+* [GitHub Pages](https://github.com/peaceiris/actions-gh-pages)
+
+**Parameters**:
+
+| Parameter | Since | Required           | Default                     | Description         | 
+|-----------|-------|--------------------|-----------------------------|---------------------|
+| path      | 3.1.0 | :heavy_minus_sign: | `./`                        | Path with docs      |
+| playbook  | 3.1.0 | :heavy_minus_sign: | `local-antora-playbook.yml` | Playbook file name  |
+| publish   | 3.1.0 | :heavy_minus_sign: | false                       | Publish to GH Pages |
+
+**How to use**:
+
+```yaml
+uses: playframework/.github/.github/workflows/antora.yml@v3
+```
+
 ## GitHub Actions Starter workflows
 
 TODO