Add github action to generate and push docs to docs branch

Instead of requiring that users regenerate auto-generated documentation
each time it changes, this adds a github action to force push any
changes on the main branch to the docs branch.  Github pages allows
docs to be on any branch, in the docs folder.

There may be some permissions issues with the docs branch.  In that
case, I'm fine reverting this immediately afterwards.  I've tested this
to the extent I could on my forked repository.

Author: David Freese

.bazelci/presubmit.yml

@@ -78,14 +78,6 @@ tasks:
     working_directory: examples
     test_targets:
       - //...
-  docs_linux:
-    name: Docs
-    platform: ubuntu1804
-    working_directory: docs
-    build_targets:
-      - //...
-    run_targets:
-      - "//:test_docs"
   clippy_examples:
     name: Clippy on Examples
     platform: ubuntu1804

.github/workflows/gen_docs.yaml

@@ -0,0 +1,18 @@
+name: Generate Documenation Pages
+on:
+  push:
+    branches:
+      - main
+jobs:
+  generate:
+		if: ${{ github.repository_owner == 'bazelbuild' }}
+    name: Generate Docs
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install bazelisk
+        run: .github/workflows/scripts/install_bazelisk.sh
+        env:
+          USE_BAZEL_VERSION: 4.0.0
+      - name: Generate and Push
+        run: .github/workflows/scripts/publish_docs.sh

.github/workflows/scripts/install_bazelisk.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+
+curl -LO "https://github.com/bazelbuild/bazelisk/releases/download/v1.1.0/bazelisk-linux-amd64"
+mkdir -p "${GITHUB_WORKSPACE}/bin/"
+mv bazelisk-linux-amd64 "${GITHUB_WORKSPACE}/bin/bazel"
+chmod +x "${GITHUB_WORKSPACE}/bin/bazel"

.github/workflows/scripts/publish_docs.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+set -exuo pipefail
+
+# run within the docs workspace
+pushd docs &> /dev/null
+
+# We use a bazelisk-installed bazel
+"${GITHUB_WORKSPACE}/bin/bazel" clean
+"${GITHUB_WORKSPACE}/bin/bazel" build //...
+
+# Pull out the relevant docs
+cp bazel-bin/*.md .
+chmod 0644 *.md
+
+# And generate a new commit, that we push to the "docs" branch.
+git config user.name github-actions
+git config user.email [email protected]
+git add *.md
+git commit -m "Regenerate documentation"
+git remote -v
+git push -f origin HEAD:docs
+
+popd &> /dev/null
+