Set up documentation website generation and deployment (#253)

Generating the website is done by Jekyll with a theme called `just-the-docs`. 
Deployment of the website is done via GitHub Pages.

See:
- https://github.com/jekyll/jekyll
- https://github.com/just-the-docs/just-the-docs

.github/workflows/build.yaml

@@ -2,8 +2,7 @@ name: Build and verify
 on:
   pull_request:
   push:
-    branches:
+    branches: [$default-branch]
-      - 'master'
 permissions:
   contents: read
 jobs:

.github/workflows/deploy-website.yaml

@@ -0,0 +1,45 @@
+name: Update `error-prone.picnic.tech` website content
+on:
+  pull_request:
+  push:
+    branches: [$default-branch]
+permissions:
+  contents: read
+  id-token: write
+  pages: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3.0.2
+      - name: Configure Github Pages
+        uses: actions/configure-pages@v2.1.1
+      - name: Generate documentation
+        run: ./generate-docs.sh
+      - name: Build website with Jekyll
+        uses: actions/jekyll-build-pages@v1.0.5
+        with:
+          source: website/
+          destination: ./_site
+      - name: Validate HTML output
+        uses: anishathalye/proof-html@v1.4.1
+        with:
+          directory: ./_site
+          check_external_hash: false
+      - name: Upload website as artifact
+        uses: actions/upload-pages-artifact@v1.0.4
+  deploy:
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    needs: build
+    runs-on: ubuntu-22.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1.2.1

README.md

@@ -1,10 +1,10 @@
 <div align="center">
-
   <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="logo-dark.svg">
+    <source media="(prefers-color-scheme: dark)" srcset="website/assets/images/logo-dark.svg">
-  <source media="(prefers-color-scheme: light)" srcset="logo.svg">
+    <source media="(prefers-color-scheme: light)" srcset="website/assets/images/logo.svg">
-  <img alt="Error Prone Support logo" src="logo.svg" width="50%">
+    <img alt="Error Prone Support logo" src="website/assets/images/logo.svg" width="50%">
   </picture>
+</div>
 
 # Error Prone Support
 
@@ -24,8 +24,6 @@ focussing on maintainability, consistency and avoidance of common pitfalls.
 [Developing Error Prone Support](#-developing-error-prone-support) •
 [How it works](#-how-it-works) • [Contributing](#%EF%B8%8F-contributing)
 
-</div>
-
 ---
 
 ## ⚡ Getting started
@@ -201,9 +199,9 @@ Want to report or fix a bug, suggest or add a new feature, or improve the
 documentation? That's awesome! Please read our [contribution
 guidelines][contributing].
 
-[bug-checks]: error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/
+[bug-checks]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/
-[bug-checks-identity-conversion]: error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/IdentityConversion.java
+[bug-checks-identity-conversion]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/IdentityConversion.java
-[contributing]: CONTRIBUTING.md
+[contributing]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/CONTRIBUTING.md
 [error-prone-bugchecker]: https://github.com/google/error-prone/blob/master/check_api/src/main/java/com/google/errorprone/bugpatterns/BugChecker.java
 [error-prone-fork-jitpack]: https://jitpack.io/#PicnicSupermarket/error-prone
 [error-prone-fork-repo]: https://github.com/PicnicSupermarket/error-prone
@@ -215,7 +213,7 @@ guidelines][contributing].
 [google-java-format]: https://github.com/google/google-java-format
 [idea-288052]: https://youtrack.jetbrains.com/issue/IDEA-288052
 [license-badge]: https://img.shields.io/github/license/PicnicSupermarket/error-prone-support
-[license]: LICENSE.md
+[license]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/LICENSE.md
 [maven-central-badge]: https://img.shields.io/maven-central/v/tech.picnic.error-prone-support/error-prone-support?color=blue
 [maven-central-search]: https://search.maven.org/artifact/tech.picnic.error-prone-support/error-prone-support
 [maven]: https://maven.apache.org
@@ -224,5 +222,5 @@ guidelines][contributing].
 [pitest-maven]: https://pitest.org/quickstart/maven
 [pr-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg
 [refaster]: https://errorprone.info/docs/refaster
-[refaster-templates-bigdecimal]: error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates/BigDecimalTemplates.java
+[refaster-templates-bigdecimal]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates/BigDecimalTemplates.java
-[refaster-templates]: error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates/
+[refaster-templates]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates/

generate-docs.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+set -e -u -o pipefail
+
+REPOSIORY_ROOT="$(git rev-parse --show-toplevel)"
+WEBSITE_ROOT="${REPOSIORY_ROOT}/website"
+
+generate_homepage() {
+    local homepage="${WEBSITE_ROOT}/index.md"
+
+    echo "Generating ${homepage}..."
+    cat - "${REPOSIORY_ROOT}/README.md" > "${homepage}" << EOF
+---
+layout: default
+title: Home
+nav_order: 1
+---
+EOF
+
+    local macos_compat=""
+    [[ "${OSTYPE}" == "darwin"* ]] && macos_compat="yes"
+    sed -i ${macos_compat:+".bak"} 's/src="website\//src="/g' "${homepage}"
+    sed -i ${macos_compat:+".bak"} 's/srcset="website\//srcset="/g' "${homepage}"
+}
+
+# Generate the website.
+generate_homepage

website/.gitignore

@@ -0,0 +1,12 @@
+# Generated by Bundler and Jekyll.
+.bundle/
+Gemfile.lock
+.jekyll-cache/
+.jekyll-metadata
+.sass-cache/
+_site/
+vendor/
+
+# Generated by `../generate-docs.sh`.
+*.bak
+index.md

website/404.md

@@ -0,0 +1,11 @@
+---
+layout: default
+title: Page not found
+permalink: /404
+nav_exclude: true
+search_exclude: true
+---
+
+## Page not found :(
+
+The requested page could not be found.

website/Gemfile

@@ -0,0 +1,5 @@
+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"

website/README.md

@@ -0,0 +1,38 @@
+# Error Prone Support website
+
+This directory contains the majority of the source code that powers
+[error-prone.picnic.tech][error-prone-support-website]. The website is
+statically generated using [Jekyll][jekyll].
+
+# Local development
+
+To view the website on `localhost`, first follow the [Jekyll installation
+instructions][jekyll-docs-installation]. Once done, in this directory execute:
+
+```sh
+bundle install
+../generate-docs.sh && bundle exec jekyll serve --livereload
+```
+
+The website will now be [available][localhost-port-4000] on port 4000. Source
+code modifications (including the result of rerunning `../generate-docs.sh`)
+will automatically be reflected. (An exception is `_config.yml`: changes to
+this file require a server restart.) Subsequent server restarts do not require
+running `bundle install`, unless `Gemfile` has been updated in the interim.
+
+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.
+
+# Deployment
+
+The website is regenerated and deployed using the
+[`deploy-website.yaml`][error-prone-support-website-deploy-workflow] GitHub
+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/
+[localhost-port-4000]: http://127.0.0.1:4000

website/_config.yml

@@ -0,0 +1,46 @@
+# General configuration.
+title: Error Prone Support
+logo: assets/images/favicon.svg
+url: https://error-prone.picnic.tech
+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/just-the-docs@v0.4.0.rc2
+plugins:
+  - jekyll-remote-theme
+  - jekyll-sitemap
+
+# Files and directories not to be deployed through GitHub pages.
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - README.md
+  - vendor
+
+# See https://jekyllrb.com/docs/permalinks/#built-in-formats.
+permalink: pretty
+
+# Theme (just-the-docs) configuration.
+# See
+# https://just-the-docs.github.io/just-the-docs/docs/navigation-structure/#external-navigation-links.
+nav_external_links:
+  - title: Error Prone Support on GitHub
+    url: https://github.com/PicnicSupermarket/error-prone-support
+    hide_icon: false
+
+# SEO configuration.
+# See https://jekyll.github.io/jekyll-seo-tag/usage.
+social:
+  name: Picnic
+  links:
+    - https://github.com/PicnicSupermarket
+    - https://twitter.com/picnic
+    - https://www.linkedin.com/company/picnictechnologies
+twitter:
+  username: picnic
+  card: summary

website/_includes/footer_custom.html

@@ -0,0 +1,5 @@
+<img src="/assets/images/picnic-logo@2x.png" alt="Picnic Logo" id="logo" />
+
+<p align="center">
+    Copyright &copy; 2017-2022 Picnic Technologies BV
+</p>

website/_includes/head_custom.html

@@ -0,0 +1,18 @@
+<!-- Generated using https://realfavicongenerator.net. -->
+<link rel="apple-touch-icon" sizes="180x180" href="/assets/images/apple-touch-icon.png">
+<link rel="icon" type="image/png" sizes="32x32" href="/assets/images/favicon-32x32.png">
+<link rel="icon" type="image/png" sizes="16x16" href="/assets/images/favicon-16x16.png">
+<link rel="manifest" href="/assets/images/site.webmanifest">
+<link rel="mask-icon" href="/assets/images/safari-pinned-tab.svg" color="#5bbad5">
+<link rel="shortcut icon" href="/favicon.ico">
+<meta name="msapplication-TileColor" content="#da532c">
+<meta name="msapplication-config" content="/assets/images/browserconfig.xml">
+<meta name="theme-color" content="#ffffff">
+
+<!-- XXX: The theme does not natively support both light and dark mode. Drop
+this section once https://github.com/just-the-docs/just-the-docs/issues/234 is
+resolved. -->
+<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-light.css' | relative_url }}"
+    media="(prefers-color-scheme: light)">
+<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-dark.css' | relative_url }}"
+    media="(prefers-color-scheme: dark)">

website/_sass/custom/custom.scss

@@ -0,0 +1,21 @@
+// XXX: We should override `$nav-width(-md)`, but this breaks code highlighting
+// and other styles. See
+// https://github.com/just-the-docs/just-the-docs/issues/982.
+// Once the fix for the above issue is released, replace this section with the
+// approach recommended at
+// https://just-the-docs.github.io/just-the-docs/docs/customization/#custom-schemes.
+@include mq(lg) {
+    .side-bar {
+        min-width: 400px;
+    }
+
+    .site-nav, .site-header {
+        width: 400px;
+    }
+}
+
+footer > img#logo {
+    width: 2rem;
+    margin: 0 auto;
+    display: block;
+}

website/assets/images/browserconfig.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<browserconfig>
+    <msapplication>
+        <tile>
+            <square150x150logo src="/assets/images/mstile-150x150.png"/>
+            <TileColor>#da532c</TileColor>
+        </tile>
+    </msapplication>
+</browserconfig>

website/assets/images/safari-pinned-tab.svg

@@ -0,0 +1,88 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
+ "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
+<svg version="1.0" xmlns="http://www.w3.org/2000/svg"
+ width="2623.000000pt" height="2623.000000pt" viewBox="0 0 2623.000000 2623.000000"
+ preserveAspectRatio="xMidYMid meet">
+<metadata>
+Created by potrace 1.14, written by Peter Selinger 2001-2017
+</metadata>
+<g transform="translate(0.000000,2623.000000) scale(0.100000,-0.100000)"
+fill="#000000" stroke="none">
+<path d="M12907 25594 c-1 -1 -87 -5 -190 -9 -104 -3 -207 -8 -230 -10 -23 -2
+-78 -7 -122 -10 -44 -3 -109 -8 -145 -11 -36 -2 -78 -6 -95 -9 -16 -2 -59 -6
+-95 -10 -36 -3 -76 -8 -90 -10 -14 -2 -50 -7 -80 -10 -30 -4 -66 -8 -80 -10
+-14 -2 -61 -9 -105 -15 -44 -6 -91 -13 -105 -16 -14 -2 -41 -7 -60 -10 -461
+-71 -1060 -217 -1545 -378 -124 -41 -379 -132 -410 -146 -11 -5 -67 -28 -125
+-51 -505 -197 -1190 -545 -1630 -827 -82 -52 -373 -246 -385 -255 -5 -5 -53
+-38 -105 -75 -239 -168 -595 -450 -796 -631 -27 -25 -93 -84 -145 -130 -114
+-103 -545 -533 -650 -651 -156 -173 -189 -212 -316 -365 -32 -39 -71 -88 -88
+-108 -16 -21 -35 -44 -40 -50 -23 -26 -207 -269 -282 -372 -118 -163 -384
+-564 -437 -660 -6 -11 -43 -74 -82 -140 -39 -66 -88 -151 -108 -188 -20 -37
+-46 -84 -58 -105 -12 -20 -71 -136 -132 -257 -101 -200 -142 -285 -199 -415
+-11 -25 -31 -70 -44 -100 -72 -159 -275 -683 -298 -770 -3 -14 -12 -41 -20
+-60 -21 -55 -127 -402 -149 -490 -2 -8 -18 -68 -36 -134 -17 -65 -34 -130 -36
+-145 -3 -14 -16 -71 -29 -126 -24 -104 -37 -161 -36 -170 0 -2 -4 -19 -9 -36
+-5 -18 -12 -50 -16 -73 -3 -22 -7 -43 -9 -46 -2 -4 -7 -29 -11 -56 -3 -27 -8
+-52 -10 -55 -2 -4 -6 -24 -9 -45 -3 -22 -10 -61 -15 -89 -6 -27 -12 -68 -15
+-90 -3 -22 -8 -51 -10 -65 -3 -14 -7 -42 -10 -62 -3 -21 -7 -55 -10 -75 -3
+-21 -7 -49 -10 -63 -2 -14 -7 -52 -10 -85 -3 -33 -7 -71 -10 -85 -5 -28 -13
+-106 -20 -195 -3 -33 -7 -78 -10 -100 -2 -22 -7 -83 -10 -135 -4 -52 -9 -122
+-11 -155 -3 -33 -7 -269 -10 -525 -3 -256 -9 -468 -12 -472 -4 -3 -29 -19 -57
+-35 -203 -116 -785 -512 -935 -636 -8 -7 -65 -51 -125 -97 -119 -92 -382 -308
+-455 -374 -25 -23 -79 -70 -120 -106 -273 -240 -657 -632 -850 -870 -320 -394
+-512 -753 -546 -1020 -25 -193 12 -365 112 -516 127 -192 309 -298 601 -348
+174 -30 530 -26 747 8 17 3 54 8 81 11 28 4 57 8 65 10 8 2 35 7 60 10 25 3
+52 8 60 10 8 2 31 7 50 10 19 3 87 17 150 31 63 15 121 27 130 29 36 8 266 69
+395 106 109 31 572 182 632 205 8 4 11 -466 11 -1913 0 -1055 3 -1952 6 -1993
+41 -532 186 -1020 438 -1475 82 -149 279 -437 355 -520 10 -11 45 -52 78 -90
+109 -127 291 -302 440 -423 89 -72 374 -272 389 -272 2 0 33 -18 69 -39 82
+-50 369 -191 388 -191 8 0 19 -4 25 -9 9 -9 52 -26 214 -82 182 -64 401 -114
+660 -154 27 -4 95 -11 205 -21 135 -12 518 -5 615 10 14 3 52 7 85 11 33 3 69
+8 80 10 11 3 37 7 57 10 21 2 57 9 80 14 24 6 57 12 73 15 17 3 66 15 110 26
+44 12 88 23 98 25 101 22 417 140 572 214 53 25 82 34 86 27 4 -6 10 -36 13
+-66 4 -30 11 -77 16 -105 5 -27 11 -61 14 -75 4 -27 13 -79 20 -120 7 -37 22
+-111 51 -245 14 -66 27 -131 30 -145 3 -14 27 -115 55 -225 28 -110 52 -207
+54 -215 11 -46 28 -107 33 -120 3 -8 7 -19 8 -25 9 -39 27 -104 35 -125 5 -14
+23 -72 40 -130 63 -208 154 -476 227 -665 74 -190 87 -224 145 -360 111 -257
+276 -584 372 -735 42 -65 150 -225 155 -230 4 -3 22 -26 41 -53 70 -96 196
+-227 288 -301 159 -127 307 -186 481 -191 401 -11 693 267 904 861 58 163 130
+425 152 554 3 19 10 53 15 75 5 22 12 60 15 85 4 24 8 47 10 50 1 3 6 28 9 55
+4 28 9 57 11 65 2 8 7 36 10 62 5 46 8 73 20 153 6 43 10 75 20 170 4 33 8 71
+10 85 1 14 5 61 9 105 4 44 9 96 11 115 4 34 19 257 24 366 1 21 2 21 119 -12
+124 -36 334 -88 392 -98 19 -3 46 -8 60 -11 14 -3 36 -7 50 -10 14 -3 34 -7
+45 -9 32 -6 226 -35 278 -41 26 -3 66 -7 90 -10 245 -31 756 -36 997 -11 19 2
+67 7 105 11 71 6 80 7 170 19 159 21 359 60 575 111 193 45 635 192 712 235
+29 16 38 12 81 -37 211 -238 328 -363 532 -568 197 -197 293 -283 429 -385 26
+-19 53 -40 60 -47 24 -21 239 -164 311 -206 69 -41 319 -167 330 -167 3 0 24
+-8 48 -19 219 -98 513 -170 797 -197 54 -5 382 -5 408 1 13 2 52 7 86 10 68 6
+255 38 298 51 9 3 25 6 35 8 86 17 315 89 423 133 251 102 409 200 545 338
+149 151 214 297 220 492 9 309 -179 590 -595 887 -138 99 -400 252 -560 326
+l-66 31 -53 104 c-28 57 -72 141 -97 186 -24 45 -43 84 -41 86 2 1 28 -7 58
+-18 78 -29 296 -97 379 -118 71 -18 221 -49 270 -57 84 -13 75 -11 220 -29
+174 -22 537 -22 723 -1 26 3 68 8 94 11 111 12 280 45 416 81 32 8 68 17 80
+20 65 12 444 150 504 183 10 6 69 35 131 66 98 48 327 179 342 195 3 3 38 27
+78 54 40 27 101 71 135 97 34 27 67 52 72 56 77 57 356 325 440 423 28 32 139
+170 157 195 4 5 18 24 31 40 85 108 258 396 337 560 108 226 224 560 266 768
+25 125 50 281 59 377 3 25 8 70 12 100 3 30 7 930 8 2000 2 1667 4 1945 16
+1942 8 -2 106 -34 219 -72 175 -58 327 -107 365 -116 6 -1 51 -14 100 -29 106
+-31 397 -105 440 -112 17 -2 55 -11 85 -18 30 -8 82 -18 115 -24 33 -6 74 -13
+90 -16 279 -51 619 -72 848 -52 379 34 643 195 764 465 75 169 78 383 8 599
+-38 115 -152 341 -245 482 -183 280 -375 506 -715 846 -198 199 -347 339 -494
+465 -36 30 -72 62 -80 70 -9 8 -66 55 -126 105 -61 49 -115 94 -121 100 -6 5
+-26 21 -44 35 -18 14 -81 62 -139 107 -133 103 -129 101 -311 235 -165 121
+-495 341 -695 462 l-80 48 -1 346 c0 304 -9 625 -19 732 -2 19 -6 78 -10 130
+-4 52 -8 108 -10 125 -2 16 -6 59 -9 95 -6 64 -9 88 -21 185 -11 88 -14 115
+-19 153 -3 20 -8 57 -11 82 -3 25 -8 56 -10 70 -3 14 -7 40 -10 58 -3 17 -7
+44 -10 60 -2 15 -7 43 -10 62 -18 111 -30 174 -65 345 -22 105 -49 228 -60
+275 -11 47 -23 95 -25 108 -11 47 -77 293 -115 422 -221 761 -566 1552 -987
+2265 -97 163 -104 175 -278 438 -688 1039 -1542 1917 -2595 2667 -133 95 -576
+380 -590 380 -6 0 -10 5 -10 10 0 6 -4 10 -9 10 -5 0 -55 27 -111 60 -56 33
+-104 60 -107 60 -3 0 -17 8 -31 18 -38 27 -156 89 -397 212 -546 277 -1134
+507 -1740 680 -99 29 -187 53 -195 55 -8 2 -89 22 -180 44 -91 23 -178 44
+-195 47 -16 3 -46 9 -65 14 -19 5 -51 12 -70 15 -19 3 -42 8 -50 10 -8 2 -26
+6 -40 9 -38 6 -142 25 -170 31 -33 7 -127 23 -170 29 -19 3 -48 8 -65 11 -64
+11 -92 15 -140 20 -27 3 -75 10 -105 15 -30 5 -86 12 -125 15 -38 4 -77 8 -85
+10 -28 5 -171 18 -330 30 -52 4 -111 8 -130 10 -114 10 -835 26 -843 19z"/>
+</g>
+</svg>

website/assets/images/site.webmanifest

@@ -0,0 +1,19 @@
+{
+    "name": "Error Prone Support documentation",
+    "short_name": "Error Prone Support",
+    "icons": [
+        {
+            "src": "/assets/images/android-chrome-192x192.png",
+            "sizes": "192x192",
+            "type": "image/png"
+        },
+        {
+            "src": "/assets/images/android-chrome-512x512.png",
+            "sizes": "512x512",
+            "type": "image/png"
+        }
+    ],
+    "theme_color": "#ffffff",
+    "background_color": "#ffffff",
+    "display": "standalone"
+}

website/bugpatterns.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: Bug Patterns
+nav_order: 2
+has_children: true
+---
+
+# Bug Patterns

website/refastertemplates.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: Refaster templates
+nav_order: 2
+has_children: true
+---
+
+# Refaster templates