Add GitHub Actions workflow to update GitHub Pages

[snprajwal]

The API docs for this project is hosted at
https://swiftlang.github.io/swift-docc/documentation/swift-docc. These docs had to be manually updated by running
bin/update-gh-pages-documentation-site frequently. Introduce a GitHub Actions workflow that automatically updates the docs upon merge. The identity of the merge author is used to create the commit with the updated docs.

[heckj]

Do you want to keep pushing these to GitHub Pages to verify the process? Because they're included in the combined docs now for swift.org - github.com/swiftlang/docs which builds out docs.swift.org/main/documentation (and docs.swift.org/latest/documentation)

[d-ronnqvist]

Do you want to keep pushing these to GitHub Pages to verify the process? Because they're included in the combined docs now for swift.org - github.com/swiftlang/docs which builds out docs.swift.org/main/documentation (and docs.swift.org/latest/documentation)

We push library / contributor documentation to GitHub Pages and more high-level user-facing documentation about the DocC tool and syntax to swift.org.

[d-ronnqvist]

If we'll push to GitHub pages automatically, do we still need bin/update-gh-pages-documentation-site or can we remove that script?

[d-ronnqvist]

I'm mostly just curious where the _site component comes from. AFAICT we don't specify it in bin/update-gh-pages-documentation-site and I'm not sure how that script compares to running a GH "action".

[snprajwal]

The script uses a separate worktree, whereas the action builds into the existing worktree in an untracked directory, and then copies that over to replace the docs directory on the gh-pages branch. I semi-arbitrarily picked _site as a prefix so we don't get confused with the source and target directories when reading the logs, but it can be anything we want.

I've seen other web frontend projects, e.g. Webpack place the build output in dist/, so we can also do that if it's clearer.

[snprajwal]

If we'll push to GitHub pages automatically, do we still need bin/update-gh-pages-documentation-site or can we remove that script?

We can remove it, I've configured the action to allow manually triggering it, so if we need to rebuild for whatever reason, we're able to do that via GHA itself. I'd prefer to keep it around for at least a few runs of this action, just to make sure everything works fine, and then delete it in a separate PR.