= docs.rubocop.org
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
link:https://github.com/rubocop/rubocop/tree/master/docs[docs] folder of
RuboCop's GitHub repo (and the core RuboCop extensions like rubocop-rspec
) and
is published to https://docs.rubocop.org. link:https://antora.org[Antora] is
used to convert the manual into HTML. The filesystem layout is described
https://docs.antora.org/antora/3.1/standard-directories/[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 Antora
Installing the Antora is super simple:
Check out https://docs.antora.org/antora/3.1/install/install-antora/[the detailed installation instructions] if you run into any problems.
== Building the Site
You can build the documentation locally from this repo.
TIP: You can preview your changes by opening docs/index.html
in your favorite browser.
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 --fetch
and git push
.
NOTE: You'll need commit access to the repository for this to work.
If you want to make changes to the manual's page structure you'll have to edit link:https://github.com/rubocop/rubocop/blob/master/doc/modules/ROOT/nav.adoc[nav.adoc].
== Using Docker
If you prefer not to install Antora on your local machine, you can build the documentation inside a Docker container like this:
Then, proceed with git add
, git commit
and git push
as mentioned above.
== Updating the Playbook
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:
TIP: You need to add one such block for each new RuboCop module you're adding to the docs site.
After releases of the main RuboCop gem you also need to update the default landing version (it should always be the latest version).
== Troubleshooting
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
.