Writing docs for man pages
A primary source of help for Bundler users are the man pages: the output printed when you run
bundle help (or
bundler help). These pages can be a little tricky to format and preview, but are pretty straightforward once you get the hang of it.
bundle may be used interchangeably in the CLI. This guide uses
bundle because it’s cuter.
What goes in man pages?
We use man pages for Bundler commands used in the CLI (command line interface). They can vary in length from large (see
bundle install) to very short (see
To see a list of commands available in the Bundler CLI, type:
$ bundle help
Our goal is to have a man page for every command.
Don’t see a man page for a command? Make a new page and send us a PR! We also welcome edits to existing pages.
Creating a new man page
To create a new man page, simply create a new
.ronn file in the
For example: to create a man page for the command
bundle cookies (not a real command, sadly), I would create a file
man/bundle-cookies.ronn and add my documentation there.
Our man pages use ronn formatting, a combination of Markdown and standard man page conventions. It can be a little weird getting used to it at first, especially if you’ve used Markdown a lot.
The ronn guide formatting guide provides a good overview of the common types of formatting.
In general, make your page look like the other pages: utilize sections like
##OPTIONS and formatting like code blocks and definition lists where appropriate.
If you’re not sure if the formatting looks right, that’s ok! Make a pull request with what you’ve got and we’ll take a peek.
To preview your changes as they will print out for Bundler users, you’ll need to run a series of commands:
$ rake spec:deps
$ rake man:build
$ man man/bundle-cookies.1
If you make more changes to
bundle-cookies.ronn, you’ll need to run the
rake man:build again before previewing.
We have tests for our documentation! The most important test file to run before you make your pull request is the one for the
help command and another for documentation quality.
$ bin/rspec ./spec/commands/help_spec.rb
$ bin/rspec ./spec/quality_spec.rb