Set up documentation website generation and deployment #253
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| name: Update `error-prone.picnic.tech` website content | ||
| on: | ||
| pull_request: | ||
| push: | ||
| branches: [$default-branch] | ||
| 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/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: | ||
|
There was a problem hiding this comment. I think it would be clearer to have a newline between these two parts. There was a problem hiding this comment. Indentation already takes care of that. We also don't do that above, or in |
||
| 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 | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| #!/usr/bin/env bash | ||
|
There was a problem hiding this comment. I'll push some suggestions for this file. (Not relying on the side-effect of |
||
|
|
||
| set -e -u -o pipefail | ||
|
|
||
| WEBSITE_FOLDER="website" | ||
| HOMEPAGE="${WEBSITE_FOLDER}/index.md" | ||
|
|
||
| configure() { | ||
| cd "$(git rev-parse --show-toplevel || echo .)" || exit | ||
| } | ||
|
|
||
| generate_homepage() { | ||
| echo "Generating ${HOMEPAGE}" | ||
| cat > "${HOMEPAGE}" << EOF | ||
| --- | ||
| 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="website\//src="/g' ${HOMEPAGE} | ||
| sed $SEDOPTION 's/srcset="website\//srcset="/g' ${HOMEPAGE} | ||
| } | ||
|
|
||
| # Generate the website. | ||
| configure | ||
| generate_homepage | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| # Generated by Bundler and Jekyll. | ||
| .bundle/ | ||
| Gemfile.lock | ||
| .jekyll-cache/ | ||
| .jekyll-metadata | ||
|
Comment on lines
+4
to
+5
There was a problem hiding this comment. I don't see these Can we drop them? There was a problem hiding this comment. These, however, are standard practice. See also For example, There was a problem hiding this comment. Okay, so it aids certain dev flows. Fine to keep then. |
||
| .sass-cache/ | ||
| _site/ | ||
| vendor/ | ||
|
|
||
| # Generated by `../generate-docs.sh`. | ||
| *.bak | ||
| index.md | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| source "https://rubygems.org" | ||
| gem "github-pages", "227" | ||
|
There was a problem hiding this comment. Should we also fix the Ruby version used? See https://bundler.io/guides/gemfile_ruby.html#specifying-a-ruby-version. There was a problem hiding this comment. Would like to make part of the larger initiative, see #253 (comment) There was a problem hiding this comment. Sorry, I didn't read all of the comments so was just a drive-by comment. SGTM 👍 |
||
| gem "html-proofer", "4.4.1" | ||
| gem "just-the-docs", "0.4.0.rc2" | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| # General configuration. | ||
| title: Error Prone Support | ||
| logo: assets/images/favicon.svg | ||
| url: https://error-prone.picnic.tech | ||
| description: >- | ||
japborst marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Error Prone extensions: extra bug checkers and a large battery of Refaster | ||
| templates. | ||
|
|
||
| theme: just-the-docs | ||
| plugins: | ||
| - jekyll-sitemap | ||
|
|
||
| # Files and directories not to be deployed through GitHub pages. | ||
| exclude: | ||
| - Gemfile | ||
| - Gemfile.lock | ||
| - README.md | ||
|
There was a problem hiding this comment. I had to add There was a problem hiding this comment. Interesting... I did not have that issue 🤔 There was a problem hiding this comment. I don't have this issue either. And I also don't see the |
||
| - vendor | ||
|
|
||
| # See https://jekyllrb.com/docs/permalinks/#built-in-formats. | ||
| permalink: pretty | ||
|
|
||
| # 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 | ||
|
|
||
| # 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 | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| <img src="/assets/images/picnic-logo@2x.png" alt="Picnic Logo" id="logo" /> | ||
|
|
||
| <p align="center"> | ||
| Copyright © 2017-2022 Picnic Technologies BV | ||
| </p> |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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="/favicon.ico"> | ||
|
There was a problem hiding this comment. I guess this one is not inside There was a problem hiding this comment. Yep, some (older) browsers assume it's in the root. Also, some scrapers make this assumption. See also https://realfavicongenerator.net/faq#why_icons_in_root If we really don't want to have in the root, we could move it and disable the favicon check for There was a problem hiding this comment. Hmm, I mean "is there a way to convince Jekyll to put it into the There was a problem hiding this comment. Personally, I'm not sure if that's any better. We're already in There was a problem hiding this comment. Ack, I'll not make a further point of it then. |
||
| <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)"> | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| // We should override $nav-width(-md), however this breaks code highlighting and other styles. | ||
| // This seems to be an issue for following the recommended approach. | ||
| // See https://github.com/just-the-docs/just-the-docs/issues/982. | ||
|
There was a problem hiding this comment. Nice that you filed a bug report! I see that the issue will be fixed in the next release. When we upgrade concrete change should we make instead? (Sorry for the n00b question, I know little about this stuff.) There was a problem hiding this comment. No, this will continue to work. When that bug gets fixed, we can adhere to the official/recommended approach of creating a custom scheme and overriding See https://just-the-docs.github.io/just-the-docs/docs/customization/#custom-schemes There was a problem hiding this comment. Check. Didn't fully grok that page yet, but pushed a commit with a proposal :) |
||
| @include mq(lg) { | ||
| .side-bar { | ||
| min-width: 400px; | ||
| } | ||
japborst marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| .site-nav, .site-header { | ||
| width: 400px; | ||
| } | ||
| } | ||
|
|
||
| // Add support for external anchor icons. | ||
| .external > svg { | ||
| width: 1rem; | ||
| vertical-align: text-bottom; | ||
| } | ||
|
There was a problem hiding this comment. 👀 @japborst What does this do? I didn't see the difference 🤔 There was a problem hiding this comment. This is used for the external anchor icons, when you look at the "view source code" button. You are right that that functionality got stripped out of this PR, as that's a follow-up in There was a problem hiding this comment. Ah, check! If it's not too much work: let's (since officially the change doesn't belong here). But since we do plan to work on There was a problem hiding this comment. Fair point. Let's keep it clean. |
||
|
|
||
| // Center and shrink the footer logo. | ||
japborst marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| footer > img#logo { | ||
| width: 2rem; | ||
| margin: 0 auto; | ||
| display: block; | ||
| } | ||
japborst marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In some websites a hash is used for JS routing, which is done after loading. Disabling this to reduce false-positives.