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
2 files changed
tree: 1bf6ccb0e1e1b977c989765a5cbaa80f8f03c50a
  1. .github/
  2. site/
  3. .apk
  4. .asf.yaml
  5. .gitignore
  6. .project
  7. Gemfile
  8. Gemfile.lock
  9. LICENSE
  10. NOTICE
  11. README.md
README.md

Apache Daffodil Website

The Apache Daffodil website is based off of the Apache Website Template.

The website is generated using Jekyll and some plug-ins for it.

Testing Locally

To improve reproducibility and to minimize the effects and variability of a users environment, it is recommended that changes to the site repo be tested locally with a container. To do so, run one of the following commands.

With docker:

docker run -it --rm \
  --publish 127.0.0.1:4000:4000 \
  --volume="$PWD:/srv/jekyll" \
  docker.io/jekyll/jekyll:4.2.0 \
  jekyll serve --watch --source site

With rootless podman:

podman run -it --rm \
  --publish 127.0.0.1:4000:4000 \
  --volume="$PWD:/srv/jekyll" \
  --env JEKYLL_ROOTLESS=1 \
  docker.io/jekyll/jekyll:4.2.0 \
  jekyll serve --watch --source site

Then open http://localhost:4000 to view the site served by the Jekyll container. Changes to files in the site directory are automatically rebuilt and served.

Once satisfied, create a branch and open a pull request using the Daffodil project Code Conttributor Workflow but using the website repo instead of the code repo.

Publishing to the Live Site

Daffodil uses gitpubsub for publishing to the website. The static content served via Apache must be served in the content directory on the asf-site orphan branch. When changes are merged into the main branch on GitHub, a GitHub action will automatically run and perform the necessary steps to publish the site.