Unify local and GitHub Actions website generation flow (#274)

.github/workflows/deploy-website.yaml

@@ -16,22 +16,24 @@ jobs:
     steps:
       - name: Check out code
         uses: actions/[email protected]
+      - uses: ruby/[email protected]
+        with:
+          working-directory: ./website
+          bundler-cache: true
       - name: Configure Github Pages
         uses: actions/[email protected]
       - name: Generate documentation
         run: ./generate-docs.sh
       - name: Build website with Jekyll
-        uses: actions/[email protected]
-        with:
-          source: website/
-          destination: ./_site
+        working-directory: ./website
+        run: bundle exec jekyll build
       - name: Validate HTML output
-        uses: anishathalye/[email protected]
-        with:
-          directory: ./_site
-          check_external_hash: false
+        working-directory: ./website
+        run: bundle exec htmlproofer --check-external-hash false ./_site
       - name: Upload website as artifact
         uses: actions/[email protected]
+        with:
+          path: ./website/_site
   deploy:
     if: github.ref == 'refs/heads/master'
     needs: build

generate-docs.sh

@@ -2,14 +2,14 @@
 
 set -e -u -o pipefail
 
-REPOSIORY_ROOT="$(git rev-parse --show-toplevel)"
-WEBSITE_ROOT="${REPOSIORY_ROOT}/website"
+REPOSITORY_ROOT="$(git rev-parse --show-toplevel)"
+WEBSITE_ROOT="${REPOSITORY_ROOT}/website"
 
 generate_homepage() {
     local homepage="${WEBSITE_ROOT}/index.md"
 
     echo "Generating ${homepage}..."
-    cat - "${REPOSIORY_ROOT}/README.md" > "${homepage}" << EOF
+    cat - "${REPOSITORY_ROOT}/README.md" > "${homepage}" << EOF
 ---
 layout: default
 title: Home

website/.ruby-version

@@ -0,0 +1 @@
+3.1.2

website/Gemfile

@@ -1,5 +1,8 @@
+ruby File.read(".ruby-version").strip
+
 source "https://rubygems.org"
-gem "github-pages", "227"
 gem "html-proofer", "4.4.1"
-gem "jekyll-remote-theme", "0.4.3"
-gem "rake", "13.0.6"
+gem "jekyll", "4.2.2"
+gem "jekyll-sitemap", "1.4"
+gem "just-the-docs", "0.4.0.rc2"
+gem "webrick", "1.7"

website/README.md

@@ -24,6 +24,27 @@ If you are not familiar with Jekyll, be sure to check out its
 [documentation][jekyll-docs]. It is recommended to follow the provided
 step-by-step tutorial.
 
+###### Switch Ruby versions
+
+The required Ruby version is set in `.ruby-version`. To switch, you can use
+[rvm][rvm] to manage your Ruby version.
+
+###### Resolve Bundler issues
+
+On macOS, you may get an error such as the following when running `bundle
+install`:
+
+```sh
+fatal error: 'openssl/ssl.h' file not found
+```
+
+In that case, run:
+
+```sh
+bundle config build.eventmachine --with-cppflags="-I$(brew --prefix openssl)/include"
+bundle install
+```
+
 # Deployment
 
 The website is regenerated and deployed using the
@@ -33,6 +54,7 @@ Actions workflow any time a change is merged to `master`.
 [error-prone-support-website]: https://error-prone.picnic.tech
 [error-prone-support-website-deploy-workflow]: https://github.com/PicnicSupermarket/error-prone-support/actions/workflows/deploy-website.yaml
 [jekyll]: https://jekyllrb.com
-[jekyll-docs]: https://jekyllrb.com/docs/
-[jekyll-docs-installation]: https://jekyllrb.com/docs/installation/
+[jekyll-docs]: https://jekyllrb.com/docs
+[jekyll-docs-installation]: https://jekyllrb.com/docs/installation
 [localhost-port-4000]: http://127.0.0.1:4000
+[rvm]: https://rvm.io

website/_config.yml

@@ -6,13 +6,8 @@ description: >-
   Error Prone extensions: extra bug checkers and a large battery of Refaster
   templates.
 
-# XXX: Investigate dropping the remote theme by instead managing just-the-docs
-# using Bundler. This requires changes to the build setup. The upshot is that
-# local and CI build environments would then be in sync.
-# https://github.com/PicnicSupermarket/error-prone-support/pull/253#discussion_r982709523
-remote_theme: just-the-docs/[email protected]
+theme: just-the-docs
 plugins:
-  - jekyll-remote-theme
   - jekyll-sitemap
 
 # Files and directories not to be deployed through GitHub pages.