Add workflow to manually update documentation

Also allow the CI workflow to be manually trigger. Even though updating
the documentation pushes to the main branch, this does not trigger the
main.yml push trigger. This is a limitation with GitHub actions. So
after manually triggering the workflow to update documentation we must
also manually trigger the CI to publish that documentation change.

.github/workflows/docs.yml

@@ -0,0 +1,129 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Update Documentation
+
+# This workflow updates the documentation from the tagged daffodil release.
+# Ideally this would be triggered automatically when a daffodil release is
+# tagged, but GitHub actions does not currently have a way trigger a workflow
+# in a separate repository without adding a personal access token providing
+# authorizing the access. That would require support from Infra, which is fine,
+# it's probably just eaiser to manage it all ourselves and manually trigger
+# this workflow after a tag is created in the daffodil repo
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Daffodil tag
+        required: true
+
+jobs:
+  documentation:
+    name: Update Documentation ${{ inputs.tag }}
+    strategy:
+      matrix:
+        java_distribution: [ temurin ]
+        java_version: [ 8 ]
+        scala_version: [ 2.12.19 ]
+        os: [ ubuntu-22.04 ]
+        include:
+          - os: ubuntu-22.04
+            shell: bash
+            env_cc: clang
+            env_ar: llvm-ar-14
+          - lang: en_US
+          - encoding: UTF-8
+
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: ${{ matrix.shell }}
+    env:
+      AR: ${{ matrix.env_ar }}
+      CC: ${{ matrix.env_cc }}
+      LANG: ${{ matrix.lang }}.${{ matrix.encoding }}
+
+    steps:
+
+      ############################################################
+      # Setup
+      ############################################################
+
+      - name: Checkout Repository
+        uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+        with:
+          path: site
+
+      - name: Checkout Daffodil Repository
+        uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+        with:
+          repository: apache/daffodil
+          path: daffodil
+          ref: ${{ inputs.tag }}
+
+      - name: Verify Tag
+        run: |
+          if ! echo '${{ inputs.tag }}' | grep -q '^v.*-.*'; then echo Can only build documentation for a release candidate tag: ${{ inputs.tag }}; exit 1; fi
+          VERSION=$(echo '${{ inputs.tag }}' | sed  's/^v\(.*\)-.*$/\1/')
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Install Dependencies
+        run: |
+          sudo apt-get install -y libmxml-dev
+          sudo locale-gen $LANG
+
+      - name: Setup Java
+        uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 # v4.2.1
+        with:
+          distribution: ${{ matrix.java_distribution }}
+          java-version: ${{ matrix.java_version }}
+          cache: sbt
+
+      ############################################################
+      # Main Actions
+      ############################################################
+
+      - name: Build/Install Documentation
+        working-directory: daffodil
+        run: |
+          sbt "unidoc"
+
+          SITE_ROOT=$GITHUB_WORKSPACE/site
+
+          DOCS_DIR=$SITE_ROOT/site/docs/$VERSION
+          rm -rf $DOCS_DIR
+          mkdir -p $DOCS_DIR/{javadoc,scaladoc}/
+          cp -R target/javaunidoc/* $DOCS_DIR/javadoc/
+          cp -R target/scala-2.12/unidoc/* $DOCS_DIR/scaladoc/
+
+          TUTORIALS_DIR=$SITE_ROOT/site/tutorials
+          rm -rf $TUTORIALS_DIR
+          mkdir -p $TUTORIALS_DIR
+          cp -R tutorials/src/main/resources/* $TUTORIALS_DIR
+
+      ############################################################
+      # Post Actions
+      ############################################################
+
+      - name: Update
+        working-directory: site
+        run: |
+          # always create a commit, even if no documentation changed and the
+          # commit is empty. This is common when creating an rc2, and gives
+          # clear confirmation that this action successfully ran
+          git config --local user.email "[email protected]"
+          git config --local user.name "Apache Daffodil Site Autobuild"
+          git commit -a --allow-empty -m "Stage Daffodil release ${{ inputs.tag }}"
+          git push --force "https://${{ github.actor }}:${{ github.token }}@github.com/${{ github.repository }}.git" main

.github/workflows/main.yml

@@ -19,6 +19,7 @@ on:
   push:
   pull_request:
     types: [opened, synchronize, reopened]
+  workflow_dispatch:
 
 jobs:
   build-publish:
@@ -29,7 +30,7 @@ jobs:
 
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v2.4.0
+        uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
         with:
           fetch-depth: 0