Bootstrap documentation website

.github/workflows/build.yaml

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

.github/workflows/deploy-website.yaml

@@ -0,0 +1,41 @@
+name: Update `error-prone.picnic.tech` website contents
+on:
+  push:
+    #branches: [$default-branch]
+    branches:
+      - 'sschroevers/deploy-to-github-pages'
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out code
+        uses: actions/[email protected]
+      - name: Configure Github Pages
+        uses: actions/[email protected]
+      - name: Generate documentation
+        run:  bash ./generate-docs.sh
+      - name: Build website with Jekyll
+        uses: actions/[email protected]
+        with:
+          source: website/
+          destination: ./_site
+      - name: Upload website artifact
+        uses: actions/[email protected]
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-22.04
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/[email protected]

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: light)" srcset="logo.svg">
-  <img alt="Error Prone Support logo" src="logo.svg" width="50%">
-</picture>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="logo.svg">
+    <img alt="Error Prone Support logo" src="logo.svg" width="50%">
+  </picture>
+</div>
 
 # Error Prone Support
 
@@ -23,8 +23,6 @@ maintainability, consistency and avoidance of common gotchas.
 [Getting started](#-getting-started) • [Building](#-building) •
 [How it works](#-how-it-works) • [Contributing](#%EF%B8%8F-contributing)
 
-</div>
-
 ---
 
 ## ⚡ Getting started

docs/bugpatterns/EmptyMethod.md

@@ -0,0 +1 @@
+There's not much use to keep empty methods.

docs/refastertemplates/BigDecimalTemplates.md

@@ -0,0 +1,12 @@
+## Problem
+
+The results of the `BigDecimal` constructor can be somewhat unpredictable. One
+might assume that writing `new BigDecimal(0.1)` in Java creates a `BigDecimal`
+which is exactly equal to `0.1` (an unscaled value of `1`, with a scale of
+`1`), but it is actually equal to
+`0.1000000000000000055511151231257827021181583404541015625`. 
+
+This is because
+`0.1` cannot be represented exactly as a `double` (or, for that matter, as a
+binary fraction of any finite length). Thus, the value that is being passed in
+to the constructor is not exactly equal to `0.1`, appearances notwithstanding.

generate-docs.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+
+WEBSITE_FOLDER="website"
+DOCS_FOLDER="docs"
+
+BUGPATTERN_FOLDER="${WEBSITE_FOLDER}/bugpatterns"
+BUGPATTERN_DOCS_FOLDER="${DOCS_FOLDER}/bugpatterns"
+
+REFASTER_FOLDER="${WEBSITE_FOLDER}/refastertemplates"
+REFASTER_DOCS_FOLDER="${DOCS_FOLDER}/refastertemplates"
+
+HOMEPAGE="${WEBSITE_FOLDER}/index.md"
+
+configure() {
+    cd "$(git rev-parse --show-toplevel || echo .)"
+    mkdir "${BUGPATTERN_FOLDER}" 2>/dev/null
+    mkdir "${REFASTER_FOLDER}" 2>/dev/null
+}
+
+generate_homepage() {
+    echo "Generating ${HOMEPAGE}"
+    cat > "${HOMEPAGE}" << EOF
+---
+# Do not modify. This file is generated.
+layout: default
+title: Home
+nav_order: 1
+---
+EOF
+
+    cat "README.md" >> ${HOMEPAGE}
+
+    SEDOPTION="-i"
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        SEDOPTION="-i .bak"
+    fi
+    sed $SEDOPTION 's/src="/src="assets\/images\//g' ${HOMEPAGE}
+    sed $SEDOPTION 's/srcset="/srcset="assets\/images\//g' ${HOMEPAGE}
+}
+
+generate_bugpattern_docs() {
+    BUGPATTERNS=$(find error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns -type f -iname "*.java" ! -iname "package-info.java")
+    for BUGPATTERN in $BUGPATTERNS; do
+        NAME=$(basename "${BUGPATTERN}" ".java")
+        FILENAME="${BUGPATTERN_FOLDER}/${NAME}.md"
+
+        EXTRA_DOCS=$(cat "${BUGPATTERN_DOCS_FOLDER}/${NAME}.md" 2>/dev/null)
+
+        echo "Generating ${FILENAME}"
+        cat > "${FILENAME}" << EOF
+---
+# Do not modify. This file is generated.
+layout: default
+title: ${NAME}
+parent: Bug Patterns
+nav_order: 1
+---
+
+# ${NAME}
+
+Simplification
+{: .label .label-blue }
+
+Suggestion
+{: .label .label-yellow }
+
+${EXTRA_DOCS}
+
+## Samples
+
+\`\`\`java
+public static void sample() {}
+\`\`\`
+
+<a href="https://github.com/PicnicSupermarket/error-prone-support/blob/master/${BUGPATTERN}" class="fs-3 btn external" target="_blank">
+    View source code on GitHub
+    <svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>
+</a>
+EOF
+    done
+}
+
+generate_refaster_docs() {
+    TEMPLATES=$(find error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates -type f -iname "*.java" ! -iname "package-info.java")
+    for TEMPLATE in $TEMPLATES; do
+        NAME=$(basename "${TEMPLATE}" ".java")
+        FILENAME="${REFASTER_FOLDER}/${NAME}.md"
+
+        EXTRA_DOCS=$(cat "${REFASTER_DOCS_FOLDER}/${NAME}.md" 2>/dev/null)
+
+        echo "Generating ${FILENAME}"
+        cat > "${FILENAME}" << EOF
+---
+# Do not modify. This file is generated.
+layout: default
+title: ${NAME}
+parent: Refaster templates
+nav_order: 1
+---
+
+# ${NAME}
+
+Style
+{: .label .label-blue }
+
+Error
+{: .label .label-red }
+
+${EXTRA_DOCS}
+
+## Samples
+
+\`\`\`java
+public static void sample() {}
+\`\`\`
+
+<a href="https://github.com/PicnicSupermarket/error-prone-support/blob/master/${TEMPLATE}" class="fs-3 btn external">
+    View source code on GitHub
+    <svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>
+</a>
+EOF
+    done
+}
+
+# Do it
+configure
+generate_homepage
+generate_bugpattern_docs
+generate_refaster_docs

website/.gitignore

@@ -0,0 +1,10 @@
+# Jekyll generated files
+Gemfile.lock
+.sass-cache
+_site/
+
+# Generated content
+*.bak
+index.md
+bugpatterns/
+refastertemplates/

website/404.md

@@ -0,0 +1,9 @@
+---
+layout: default
+nav_exclude: true
+search_exclude: true
+---
+
+## Page not found :(
+
+The requested page could not be found.

website/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+gem "github-pages", "~> 227"
+gem "rake", "~> 13.0"

website/README.md

@@ -0,0 +1,44 @@
+# 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 webite 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 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.
+
+Documentation can be re-generated whist jekyll is running, by executing:
+
+```sh
+../generate-docs.sh
+```
+
+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-deploy-workflow]: https://github.com/PicnicSupermarket/error-prone-support/actions/workflows/deploy-website.yaml
+[error-prone-support-website]: https://error-prone.picnic.tech
+[jekyll-docs]: https://jekyllrb.com/docs/
+[jekyll-docs-installation]: https://jekyllrb.com/docs/installation/
+[jekyll]: https://jekyllrb.com
+[localhost-port-4000]: http://127.0.0.1:4000

website/_config.yml

@@ -0,0 +1,28 @@
+# General configuration.
+title: Error Prone Support
+logo: assets/images/favicon.svg
+description: >-
+  Error Prone Support is a Picnic-opinionated extension of Google's Error
+  Prone. It aims to improve code quality, focussing on maintainability,
+  consistency and avoidance of common gotchas.
+
+remote_theme: just-the-docs/just-the-docs
+plugins:
+- jekyll-remote-theme
+
+# Do not deploy through GitHub pages.
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - README.md
+
+permalink: pretty
+
+# Theme configuration.
+search_enabled: true
+heading_anchors: true
+
+nav_external_links:
+  - title: Error Prone Support on GitHub
+    url: https://github.com/PicnicSupermarket/error-prone-support
+    hide_icon: false

website/_includes/footer_custom.html

@@ -0,0 +1,3 @@
+<p align="center">
+    Copyright &copy; 2017-2022 Picnic Technologies BV
+</p>

website/_includes/head_custom.html

@@ -0,0 +1,17 @@
+<!-- Generated from 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="/assets/images/favicon.ico">
+<meta name="msapplication-TileColor" content="#da532c">
+<meta name="msapplication-config" content="/assets/images/browserconfig.xml">
+<meta name="theme-color" content="#ffffff">
+
+<!-- Support light and dark mode, as it's not natively supported.
+    See: https://github.com/just-the-docs/just-the-docs/issues/234 -->
+<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,15 @@
+@include mq(lg) {
+    .side-bar {
+        min-width: 400px;
+    }
+
+    .site-nav, .site-header {
+        width: 400px;
+    }
+}    
+
+.external > svg {
+    width: 1rem;
+    height: 1rem;
+    vertical-align: text-bottom;
+}

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>