My Profile Photo

rubycoloredglasses


I'm Jason, a web applications developer in the San Francisco Bay area.


Yard Documentation

Here are my own notes for using Yard to provide the Ruby API documentation and other notes for your application.

Installation

First add the Yard gem to your Gemfile, preferably in the development group if applicable.

group :development do
  # Yard
  # YARD is a Ruby Documentation tool
  # https://github.com/lsegal/yard
  gem "yard", "~> 0.8.7"
end

Running

You can use Yard to generate documentation by just running ‘Yard’ from the root of your application.

$ yard
Files:          36
Modules:        10 (   10 undocumented)
Classes:        26 (   21 undocumented)
Constants:       0 (    0 undocumented)
Methods:       140 (   54 undocumented)
 51.70% documented

You can also run a server that updates dynamically as you add documentation.

$ yard server

>> YARD 0.8.7 documentation server at http://0.0.0.0:8808
[2013-08-31 14:28:15] INFO  WEBrick 1.3.1
[2013-08-31 14:28:15] INFO  ruby 2.0.0 (2013-06-27) [x86_64-darwin12.4.1]
[2013-08-31 14:28:15] INFO  WEBrick::HTTPServer#start: pid=41901 port=8808

Configuration

You can run the ‘yardoc’ command with options that cause it to parse certain directories for documentation. With Rails applications it appears that this isn’t necessary. Rather than add options or flags after the yard command each time, you can configure a .yardopts file with the arguments you would normally use from the command line.

Yard will make use of your README.md file as the index page for the documentation, but to include other files you could configure a .yardopts file like so:

-
README.md
CHANGELOG.md

This makes it possible for the CHANGELOG to show up under the ‘File List’ section.

I prefer to have my own hierarchy of markdown files in /doc, with generated documentation in /doc/app. This way I can completed delete the doc/app folder without affecting my other markup files in the root of /doc.

--output-dir doc/app
-
doc/DevelopmentTasks.md
CHANGELOG.md
README.md

Here is a good example of a more elaborately configured .yardopts file. You can also run ‘yardoc –help’ to discover other options to add to the file.