This is an automated email from the ASF dual-hosted git repository.
slawrence pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/daffodil-site.git
The following commit(s) were added to refs/heads/main by this push:
new 7522910 Add workflow to manually update documentation from daffodil
repositories
7522910 is described below
commit 75229100ba3de1b9a57f55f1a6740e934ba2735f
Author: Steve Lawrence <[email protected]>
AuthorDate: Wed Feb 26 13:23:46 2025 -0500
Add workflow to manually update documentation from daffodil repositories
One of the steps the daffodil release candidate container did was update
the daffodil-site repository with documenation for the release candiate
(e.g. Java/Scala APIs, tutorials, VS Code documentation).
When we switch to a release workflow using GitHub action, we can no
longer do that--GitHub actions do not provide an easy way to commit to
other repositories like this daffodil-site repository.
To generate site documentation for release candidates, this adds a new
"Update Documentation" workflow to the site repository that should be
manually triggered via workflow_dispatch after the release candidate is
created. This workflow accepts the project and tag to build
documentation from, runs the appropriate commads to build the
documentation, and commits the updates to the site repo.
Note that due to GitHub actions limiations, pushing to the main branch
from this action does not trigger the CI/publish workflow that would
normally be triggered. So this also modifies the CI workflow so it can
be manually triggered. After the new "Update Documentation" workflow is
complete, we then must manually trigger the CI workflow to publish those
changes to the website.
So this means two new steps are added to a release workflow:
1. Manually trigger this workflow to build documentation
2. Manually trigger the publish workflow to build and publish the website
Although this does add a couple of extra steps to the release candidate
process, these two steps are just a couple clicks in the GitHub UI, and
the simplicity provided by switching releases to to GitHub actions
should more than makes up for it.
This also renames the 'main' workflow to 'build-publish' to make it more
clear that it publishes the website.
DAFFODIL-2791
---
.github/workflows/{main.yml => build-publish.yml} | 3 +-
.github/workflows/update-docs.yml | 128 ++++++++++++++++++++++
2 files changed, 130 insertions(+), 1 deletion(-)
diff --git a/.github/workflows/main.yml b/.github/workflows/build-publish.yml
similarity index 94%
rename from .github/workflows/main.yml
rename to .github/workflows/build-publish.yml
index 726f4cf..a29998b 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/build-publish.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/[email protected]
+ uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #
v4.1.6
with:
fetch-depth: 0
diff --git a/.github/workflows/update-docs.yml
b/.github/workflows/update-docs.yml
new file mode 100644
index 0000000..ccc6400
--- /dev/null
+++ b/.github/workflows/update-docs.yml
@@ -0,0 +1,128 @@
+# 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
+
+# Update the Daffodil site to include documentation for Daffodil or VS Code.
+# This should be manually dispatched after a release candidate is created. Note
+# that this commits the documentation to the 'main' branch of the site, but it
+# does not trigger the normal publish workflow. That must be manually
+# dispatched to actually build and publish the site with the new documentation.
+on:
+ workflow_dispatch:
+ inputs:
+ project:
+ description: Project
+ type: choice
+ options:
+ - daffodil
+ - daffodil-vscode.wiki
+ required: true
+ version:
+ description: Version (e.g. v1.0.0-rc1)
+ required: true
+
+jobs:
+ update-docs:
+ name: Update Docs ${{ inputs.project }} ${{ inputs.version }}
+ strategy:
+ matrix:
+ java_distribution: [ temurin ]
+ java_version: [ 8 ]
+
+ runs-on: ubuntu-22.04
+ env:
+ AR: llvm-ar-14
+ CC: clang
+ LANG: en_US.UTF-8
+
+ steps:
+
+ - name: Checkout Site Repository
+ uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #
v4.1.6
+ with:
+ path: site
+
+ # When building documentation for daffodil, we checkout the tag matching
+ # the version input argument. We cannot do the same for VS Code
+ # documentation since that is built from the wiki which does not use
+ # tags. For VS Code documentation, we just always build from the master
+ # branch of the wiki, so users must be careful to specify the right
+ # version when dispatching the workflow.
+ - name: Checkout Project Repository
+ uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #
v4.1.6
+ with:
+ repository: apache/${{ inputs.project }}
+ path: project
+ ref: ${{ inputs.project == 'daffodil' && inputs.version || 'master'
}}
+
+ - name: Extract Version
+ run: |
+ VERSION=$(echo '${{ inputs.version }}' | sed 's/^v\(.*\)-.*$/\1/')
+ echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+ - name: Install Dependencies
+ run: |
+ sudo apt-get install -y libmxml-dev pandoc
+
+ - name: Setup Java
+ uses: actions/setup-java@7a6d8a8234af8eb26422e24e3006232cccaa061b #
v4.6.0
+ with:
+ distribution: ${{ matrix.java_distribution }}
+ java-version: ${{ matrix.java_version }}
+
+ - name: Build Daffodil Documentation
+ working-directory: project
+ if: ${{ inputs.project == 'daffodil' }}
+ run: |
+ SITE_ROOT=${{ github.workspace }}/site
+ DOCS_DIR=$SITE_ROOT/site/docs/$VERSION
+ TUTORIALS_DIR=$SITE_ROOT/site/tutorials
+ rm -rf $DOCS_DIR
+ rm -rf $TUTORIALS_DIR
+
+ sbt unidoc
+ mkdir -p $DOCS_DIR/{javadoc,scaladoc}/
+ cp -R target/javaunidoc/* $DOCS_DIR/javadoc/
+ cp -R target/scala-*/unidoc/* $DOCS_DIR/scaladoc/
+
+ mkdir -p $TUTORIALS_DIR
+ cp -R tutorials/src/main/resources/* $TUTORIALS_DIR/
+
+ - name: Build Daffodil VS Code Documentation
+ working-directory: project
+ if: ${{ inputs.project == 'daffodil-vscode.wiki' }}
+ run: |
+ SITE_ROOT=${{ github.workspace }}/site
+ DOCS_DIR=$SITE_ROOT/site/docs/vscode/$VERSION
+ rm -rf $DOCS_DIR
+
+ DOC_NAME="Apache-Daffodil-Extension-for-Visual-Studio-Code-$VERSION"
+ mkdir -p $DOCS_DIR
+ pandoc -t docx -f markdown -o $DOCS_DIR/$DOC_NAME.docx *.md
+ pandoc -t html -f markdown -o $DOCS_DIR/$DOC_NAME.html *.md
+
+ - name: Commit Update
+ working-directory: site
+ shell: bash
+ run: |
+ # We allow empty commits so that we always create a commit. This
+ # makes it easy to verify that the workflow actually happened and
+ # didn't just silently error.
+ git add .
+ git config --local user.email "[email protected]"
+ git config --local user.name "Apache Daffodil Site"
+ git commit -a --allow-empty -m "Update documentation from ${{
inputs.project }} ${{ inputs.version }}"
+ git push --force "https://${{ github.actor }}:${{ github.token
}}@github.com/${{ github.repository }}.git" main
