yard 0.7.3 fails to build my README in both markdown and textile

Question

I've decided to convert the README file in a project of mine to markdown and have been using yard verify the documentation rendered out ok. So I installed rdiscount, changed README to README.md and tried:

yard doc README.md

which gave me a waring:

[warn]: Syntax error in `readme.md`:(3,18): syntax error, unexpected tinteger, expecting $end

So I tried:

yard doc -m markdown -- README.md

Same problem. Running:

yard doc --backtrace -- README.md

gives a little bit more info:

[warn]: Syntax error in `readme.md`:(3,18): syntax error, unexpected tinteger, expecting $end
[error]: ParserSyntaxError: syntax error in `README.md`:(3,18): syntax error, unexpected tINTEGER, expecting $end
[error]: Stack trace:
    /Users/wadewest/.rvm/gems/ruby-1.9.2-p290@peppercorn/gems/yard-0.7.3/lib/yard/parser/ruby/ruby_parser.rb:505:in `on_parse_error'
    /Users/wadewest/.rvm/gems/ruby-1.9.2-p290@peppercorn/gems/yard-0.7.3/lib/yard/parser/ruby/ruby_parser.rb:49:in `parse'
    /Users/wadewest/.rvm/gems/ruby-1.9.2-p290@peppercorn/gems/yard-0.7.3/lib/yard/parser/ruby/ruby_parser.rb:49:in `parse'
    /Users/wadewest/.rvm/gems/ruby-1.9.2-p290@peppercorn/gems/yard-0.7.3/lib/yard/parser/ruby/ruby_parser.rb:15:in `parse'
    /Users/wadewest/.rvm/gems/ruby-1.9.2-p290@peppercorn/gems/yard-0.7.3/lib/yard/parser/source_parser.rb:438:in `parse'
    /Users/wadewest/.rvm/gems/ruby-1.9.2-p290@peppercorn/gems/yard-0.7.3/lib/yard/parser/source_parser.rb:361:in `parse_in_order'

Same thing happens if I try using textile. If anyone wants to try reproduce the problem, the project is on github. Thank you.

Answer 1

I think you're just confused about the yard options. The help says this:

$ yard --help doc
Usage: yard doc [options] [source_files [- extra_files]]
(if a list of source files is omitted, 
  {lib,app}/**/*.rb ext/**/*.c is used.)

Example: yardoc -o documentation/ - FAQ LICENSE
  The above example outputs documentation for files in
  lib/**/*.rb to documentation/ including the extra files
  FAQ and LICENSE.
...

so when you say this:

$ yard doc -m markdown -- README.md

Yard will try to interpret README.md as a source file of some kind. Your README.md will be interpreted as a Ruby source file (which it isn't) and that results in a Ruby error like this:

unexpected tinteger, expecting $end

If you edit your README.md a bit you'll see the location of the error moving around but the error will make sense if you try to read README.md as a Ruby source file.

You don't need to say anything about README.md when running yard at all, yard will know what to do with README.md all by itself.