docs-workflow.yml

#
# This GitHub Actions workflow builds and deploys the re-frame documentation website hosted on GitHub Pages at:
# https://day8.github.io/re-frame/
#
# More about the build process are documented at
# https://github.com/day8/re-frame/blob/feature/mkdocs/docs/developer-notes.md

name: docs
on:
  push:
    branches: 'master'

jobs:
  # The ns-to-markdown job generates API documentation from the source code and uploads that as an artifact.
  ns-to-markdown:
    name: re-frame.core Markdown
    runs-on: ubuntu-18.04
    container:
      # Source: https://github.com/day8/dockerfile-for-dev-ci-image
      image: day8au/dev-ci:0.0.8
    steps:
      - name: Checkout Current Branch
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: Build re-frame.core Documentation
        working-directory: docs
        run: clojure -m ns-to-markdown ../src/re_frame/core.cljc > api-re-frame.core.md
      - name: Upload re-frame.core Documentation Artifact
        uses: actions/upload-artifact@v2
        with:
          name: api-re-frame.core.md
          path: docs/api-re-frame.core.md

  # Klipse is used to enable live coding in the documentation and it requires precompiled CLJS analysis cache files
  # that are built by this job then uploaded as an artifact.
  klipse-cljs-cache:
    name: Klipse CLJS Cache
    runs-on: ubuntu-18.04
    container:
      # Ref: https://github.community/t5/GitHub-Actions/docker-pull-from-public-GitHub-Package-Registry-fail-with-quot/m-p/32782
      image: superstructor/klipse:jdk-11-node-12-lumo-1.5-planck-2.25.0
    steps:
      - name: Checkout Current Branch
        uses: actions/checkout@v2
      - name: Maven cache
        id: maven-cache
        uses: actions/cache@v1
        with:
          path: /root/.m2/repository
          key: ${{ runner.os  }}-maven-klipse-${{ hashFiles('docs/klipse/project.clj') }}
      - name: Build Core CLJS Cache
        working-directory: docs/klipse
        run: ./build-cljs-cache-for-core-namespaces.sh
      - name: Build Library CLJS Cache
        working-directory: docs/klipse
        run: ./build-cljs-cache-for-lib-namespaces.sh
      - name: Create Klipse CLJS Cache Artifact
        working-directory: docs/klipse
        run: |
          tar Jcf klipse-cljs-cache.tar.xz cljs-cache
      - name: Upload Klipse CLJS Cache Artifact
        uses: actions/upload-artifact@v1
        with:
          name: klipse-cljs-cache
          path: docs/klipse/klipse-cljs-cache.tar.xz

  # MkDocs is the actual static site generator. It downloads the api-re-frame.core.md and Klipse cache artifacts then generates
  # additional files based on configuration and markdown.
  mkdocs:
    name: MkDocs
    needs:
      - ns-to-markdown
      - klipse-cljs-cache
    runs-on: ubuntu-18.04
    container:
      image: "squidfunk/mkdocs-material:5.1.1"
    steps:
      - name: Checkout Current Branch
        uses: actions/checkout@v2
      - name: Download api-re-frame.core.md Artifact
        uses: actions/download-artifact@v2
        with:
          name: api-re-frame.core.md
          path: docs
      - name: Download Klipse CLJS Cache Artifact
        uses: actions/download-artifact@v1
        with:
          name: klipse-cljs-cache
      - name: Extract Klipse CLJS Cache Artifact
        working-directory: docs/klipse
        run: tar Jxf ../../klipse-cljs-cache/klipse-cljs-cache.tar.xz
      - name: Build MkDocs Documentation
        run: mkdocs build
      - name: Create MkDocs Artifact
        run: tar zcf mkdocs.tar.gz site/
      - name: Upload MkDocs Artifact
        uses: actions/upload-artifact@v1
        with:
          name: mkdocs
          path: mkdocs.tar.gz

  # The GitHub Pages job downloads the final MkDocs artifact and commits it to the gh-pages branch for deployment.
  github-pages:
    name: GitHub Pages
    needs: mkdocs
    runs-on: ubuntu-18.04
    steps:
      - name: Checkout GitHub Pages Branch
        uses: actions/checkout@v2
        with:
          ref: "gh-pages"
          path: "gh-pages"
      - name: Download MkDocs Artifact
        uses: actions/download-artifact@v1
        with:
          name: mkdocs
      - name: Extract MkDocs Artifact
        run: |
          tar zxf mkdocs/mkdocs.tar.gz
          rm -rf gh-pages/*
          cp -Rv site/* gh-pages/
      - name: Commit
        working-directory: ./gh-pages
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add -A
          git commit -m "Update docs"
      - name: Push
        working-directory: ./gh-pages
        run: |
          REMOTE="https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
          git push "${REMOTE}" HEAD:gh-pages