To view the website on localhost, first follow the Jekyll installation instructions. Once done, run the following Maven commands in the root of the repository to extract the (test) data from the bug patterns and Refaster rule collections and to transform this data into a Jekyll-digestible format. Unless and relevant Java code has been changed, these commands needs to be executed once.

mvn -T1C clean install -DskipTests -Dverification.skip
mvn exec:java@generate-docs -pl documentation-support

Then to build the website for local development, execute in this directory:

bundle install
bundle exec jekyll serve --livereload

The website will now be available on port 4000. Source code modifications (including the result of rerunning mvn exec:java@generate-docs -pl documentation-support) 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. It is recommended to follow the provided step-by-step tutorial.

We use the Just the Docs Jekyll theme, which also includes several configuration options.

Switch Ruby versions

The required Ruby version is set in .ruby-version. To switch, you can use rvm to manage your Ruby version.

Resolve Bundler issues

On macOS, you may get an error such as the following when running bundle install:

fatal error: 'openssl/ssl.h' file not found

In that case, run:

bundle config build.eventmachine --with-cppflags="-I$(brew --prefix openssl)/include"
bundle install

Deployment

The website is regenerated and deployed using the deploy-website.yml GitHub Actions workflow any time a change is merged to master.