Setting Up a `.yardopts` File

YARD relies on a .yardopts file in the root of your project (or gem archive) to find out which source files, extra files, and formatting options you want to generate your documentation with. This file is a whitespace delimited collection of options that are passed to the yardoc executable, and therefore any valid option in yardoc is valid in the .yardopts file.

For a list of options, you can look at the yardoc options list by executing the following command on your local machine:

$ yard help doc

This of course assumes you have YARD installed :-)

Examples of .yardopts files

If you'd rather learn from example, there are a few places you can look:

  1. YARD has a good example of a .yardopts file
  2. Haml's .yardopts file
  3. Sinatra's .yardopts file
  4. Rails' .yardopts file

.document File (and YARD) also support a .document file for compatibility with RDoc. This file is simply a list of source files, and does not contain any options to YARD. Although not directly supported by RDoc, you can add extra (readme) files to the .document file if you format them in the YARD style of:

source.c files.rb here.rb - README OTHER_FILE LICENSE docs/*.md ETC

It is generally not recommended to use the .document file, as it is not as powerful as the .yardopts file, and not guaranteed to be supported by YARD if the format changes.