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.

Adornment

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.

Rabbitry

ty mu, apparently I didn't read the very top of the help. yard doc - README.md did the trick. – Adornment