Publish coverage and docs to GH Pages

Previously, the coverage reports were pushed to the wiki, but since the wiki is not meant for serving arbitrary HTML, viewing them properly required going through `raw.githack.com`. Also, the main `pkg.go.dev` site does not handle this repository well, possibly because it is a fork (also complicated by the archiving of the original) or because downloads of the package are very rare. Based on a suggestion in github (dot) com/golang/go/issues/2381, an updated GH action now downloads the contents of a local documentation server with `wget`, and modifies some local links with `sed` to get something which can be statically served. This mostly works, the main downside is that JS files seem to be missing. This adds on to the existing test step in the action, because that step is necessary for the coverage information. If additional resources are to be served on the GH Pages site, it might be a good idea to move to a separate workflow, even though it would require re-running the tests. Signed-off-by: Justin Kulikauskas <[email protected]>
JustinKuli · Jun 30, 2024 · 036e6d2 · 036e6d2
1 parent 381f3a9
commit 036e6d2
Show file tree

Hide file tree

Showing 2 changed files with 75 additions and 4 deletions.
diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml
@@ -6,6 +6,12 @@ defaults:
   run:
     shell: bash
 
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
   cleanliness:
     name: Run Cleanliness Checks
@@ -52,6 +58,13 @@ jobs:
   tests:
     name: Run Tests
     runs-on: ubuntu-latest
+
+    # Prevent race conditions from multiple runs updating the wiki or GH pages.
+    # Additional runs will be queued as needed.
+    concurrency:
+      group: tests
+      cancel-in-progress: false
+
     steps:
       - uses: actions/checkout@v4
 
@@ -63,6 +76,7 @@ jobs:
           make test
           grep -v 'zz_generated.deepcopy.go' raw-cover.out > cover.out
 
+      # This publishes a report and a badge in the wiki, which is useful for pull-requests.
       - name: Update coverage report
         uses: ncruces/go-coverage-report@v0
         with:
@@ -71,5 +85,62 @@ jobs:
           report: true
           chart: false
           amend: false
-        if: ${{ github.event_name == 'push' }}
-        continue-on-error: true
+        continue-on-error: false
+
+      # The final steps publish the report, badge, and the (newly-generated) docs to GitHub Pages.
+      # They will only run when the branch is 'main'
+      - name: GH Pages - Setup
+        if: ${{ github.ref_name == 'main' }}
+        uses: actions/configure-pages@v5
+
+      - name: GH Pages - Generate
+        if: ${{ github.ref_name == 'main' }}
+        run: |
+          go install golang.org/x/pkgsite/cmd/pkgsite@latest
+          echo "Starting the doc server..."
+          pkgsite 2>/dev/null &
+          DOC_PID=$!
+          sleep 15 # Let it initialize
+
+          echo "Downloading the generated doc site"
+          wget -r -q -np -N -E -p -k 'http://localhost:8080/open-cluster-management.io/[email protected]'
+          kill -9 $DOC_PID
+
+          echo "Bringing all the files into a gh-pages directory"
+          mv 'localhost:8080' 'gh-pages'
+          
+          # Adjust some localhost links
+          find ./gh-pages -type f -name "*.html" -print0 | \
+            xargs -0 sed -i 's|localhost:8080/files/workspaces|broken-source-link|g'
+          find ./gh-pages -type f -name "*.html" -print0 | \
+            xargs -0 sed -i 's|http://localhost:8080|https://pkg.go.dev|g'
+          
+          # Copy these from the wiki (generated by ncruces/go-coverage-report)
+          cp ./.github/wiki/main/coverage.html gh-pages/coverage.html
+          cp ./.github/wiki/main/coverage.svg gh-pages/coverage.svg
+
+          # Add a simple redirect index.html
+          cat << EOF > gh-pages/index.html
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <title>Landing Page</title>
+              <meta charset="UTF-8" />
+              <meta http-equiv="refresh" content="0; URL=./open-cluster-management.io/governance-policy-nucleus.html" />
+            </head>
+            <body>
+              <p>Redirecting to the docs page...</p>
+            </body>
+          </html>
+          EOF
+
+      - name: GH Pages - Upload
+        if: ${{ github.ref_name == 'main' }}
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './gh-pages'
+
+      - name: GH Pages - Deploy
+        if: ${{ github.ref_name == 'main' }}
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 [comment]: # " Copyright Contributors to the Open Cluster Management project "
 [![License](https://img.shields.io/:license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
 [![Go Report Card](https://goreportcard.com/badge/github.com/JustinKuli/governance-policy-nucleus)](https://goreportcard.com/report/github.com/JustinKuli/governance-policy-nucleus)
-[![Go Reference](https://pkg.go.dev/badge/image)](https://pkg.go.dev/github.com/JustinKuli/governance-policy-nucleus)
-[![Go Coverage](https://github.com/JustinKuli/governance-policy-nucleus/wiki/main/coverage.svg)](https://raw.githack.com/wiki/JustinKuli/governance-policy-nucleus/main/coverage.html)
+[![Go Reference](https://pkg.go.dev/badge/image)](https://justinkuli.github.io/governance-policy-nucleus/open-cluster-management.io/governance-policy-nucleus)
+[![Go Coverage](https://justinkuli.github.io/governance-policy-nucleus/coverage.svg)](https://justinkuli.github.io/governance-policy-nucleus/coverage.html)
 
 # Governance Policy Nucleus