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

markdown, ruby, textile, yard

Solution

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.

Problem

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.

Original source