This repository contains RuboCop’s documentation site. It’s home to both the documentation of RuboCop itself, plus that of its core extensions (the ones maintained by RuboCop’s Core Team).

The site is generated from the AsciiDoc files in the docs folder of RuboCop’s GitHub repo (and the core RuboCop extensions like rubocop-rspec) and is published to https://docs.rubocop.org. Antora is used to convert the manual into HTML. The filesystem layout is described here.

You can find a list of all the documentation modules that are weaved together in the final site in antora-playbook.yml.

To make changes to the manual you simply have to change the files under docs in the relevant repository. The docs will be regenerated manually periodically.

Installing the Antora is super simple:

Check out the detailed installation instructions if you run into any problems.

You can build the documentation locally from this repo.

Afterwards you can publish your changes like this:

You can also use the deploy script to publish changes in a single step:

It basically does antora --pull and git push.

If you want to make changes to the manual’s page structure you’ll have to edit nav.adoc.

When cutting new releases you’ll have to updated antora-playbook.yml to mention their relevant tags from which the documentation needs to be build. Here’s how this looks for one of the projects:

After releases of the main RuboCop gem you also need to update the default landing version (it should always be the latest version).

The most common mistake that people make is to forget to update the version of an Antora docs module after cutting a release. This will result in an error saying you’ve got the same version in two branches (e.g. master and v1.0). Fixing this is pretty simple - just update the version to master in antora.yml.