ci: deploy to gh-pages with GitHub Actions (#251)

Do not use the `gh-pages` branch.
Introduce a dedicated action to build the documentation content and uses
it for PR and GH Pages deployment.

.github/actions/build-documentation/action.yml

@@ -0,0 +1,20 @@
+name: 'Build the documentation'
+description: 'Build static and API documentation.'
+
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/checkout@v3
+    - name: Setup node
+      uses: actions/setup-node@v3
+      with:
+        node-version: '16'
+    - name: Install dependencies
+      shell: bash
+      run: npm ci
+    - name: Build docs
+      shell: bash
+      run: npm run api-doc
+    - name: Copy static pages
+      shell: bash
+      run: cp -r public/docs build

.github/workflows/deploy-documentation-pr.yml

@@ -0,0 +1,27 @@
+name: Generate Documentation API
+
+on:
+  pull_request:
+    branches:
+      - master
+    paths:
+      - '.github/actions/build-documentation/**/*'
+      - '.github/workflows/deploy-documentation-pr.yml'
+      - 'public/docs/**/*'
+      - 'src/**/*.ts'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'typedoc.json'
+
+jobs:
+  docs:
+    runs-on: ${{ vars.RUNNER_UBUNTU }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build documentation
+        uses: ./.github/actions/build-documentation
+      - name: Upload
+        uses: actions/upload-artifact@v3
+        with:
+          name: documentation-${{github.sha}}
+          path: build/docs

.github/workflows/deploy-documentation.yml

@@ -0,0 +1,52 @@
+name: Deploy the documentation on GitHub Pages
+
+# Controls when the workflow will run
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - '.github/actions/build-documentation/**/*'
+      - '.github/workflows/deploy-documentation-pr.yml'
+      - 'public/docs/**/*'
+      - 'src/**/*.ts'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'typedoc.json'
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ${{ vars.RUNNER_UBUNTU }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build documentation
+        uses: ./.github/actions/build-documentation
+      - name: Upload artifact for GitHub Pages
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: build/docs
+
+  deploy:
+    needs: build
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      contents: read
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ${{ vars.RUNNER_UBUNTU }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

README.md

@@ -11,8 +11,9 @@ GitHub pages environment generated by this repository
 ## Miscellaneous
 
 - [Announce new release](.github/workflows/announce-new-release.yml): post test announces on social medias (as done in the repositories of bpmn-visualization and bpmnVisualizationR)
+- [Deploy Documentation PR](.github/workflows/deploy-documentation-pr.yml): generate a TypeDoc API documentation and upload artifact (test gh-pages content in PR)
+- [Deploy Documentation](.github/workflows/deploy-documentation.yml): generate a TypeDoc API documentation and push to github-pages
 - [Fill github draft releases](.github/workflows/fill-gh-draft-release.yml): experiment the release-drafter configuration (used in bpmn-visualization)
-- [Generate Documentation API](.github/workflows/generate-documentation-api.yml): generate a TypeDoc API documentation and push to github-pages (for bpmn-visualization)
 - [Slack send message](.github/workflows/slack-send-message.yml): send a message to a Slack channel or user
 - [Surge preview for Pull Request](.github/workflows/surge-preview-for-pr.yml): create/teardown a surge deployment when a new Pull Request is created/closed  
 - [Workflow concurrency](.github/workflows/workflow-concurrency.yml): avoid to have more than 1 workflow run at a time

public/docs/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>Process Analytics Playground site</title>
+</head>
+<body>
+<section>
+    <h1>Process Analytics Playground site</h1>
+    <p>Have a look at an example of the <a href="api/">documentation of an TypeScript API generated with Typedoc</a></p>
+</section>
+<footer>Process Analytics - 2021-present</footer>
+</body>
+</html>