Set up documentation website generation and deployment #253
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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/[email protected] | ||
| - 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 | ||
| - name: Validate HTML output | ||
| uses: anishathalye/[email protected] | ||
| with: | ||
| directory: ./_site | ||
| check_external_hash: false | ||
| - name: Upload website as artifact | ||
| uses: actions/[email protected] | ||
| 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/[email protected] | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| 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 "jekyll-remote-theme", "0.4.3" | ||
| gem "rake", "13.0.6" | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # 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. | ||
|
|
||
| # 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] | ||
| plugins: | ||
| - jekyll-remote-theme | ||
| - 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 | ||
|
|
||
| # 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 | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| <img src="/assets/images/[email protected]" alt="Picnic Logo" id="logo" /> | ||
|
|
||
| <p align="center"> | ||
| Copyright © 2017-2022 Picnic Technologies BV | ||
| </p> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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)"> | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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; | ||
| } | ||
japborst marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| .site-nav, .site-header { | ||
| width: 400px; | ||
| } | ||
| } | ||
|
|
||
| footer > img#logo { | ||
| width: 2rem; | ||
| margin: 0 auto; | ||
| display: block; | ||
| } | ||
japborst marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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> |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
File renamed without changes
File renamed without changes
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.