Local documentation is ugly

[tfausak]

<span class="line-numbers"><a href="#n1" name="n1">1</a></span>gem 'active_interaction', '~> 0.1.0'

This is basically because we switched to kramdown (due to #9). Everything looks find on RubyDoc.info (which is weird), but locally it looks like garbage.

[tfausak]

It just occurred to me why everything looks fine on RubyDoc.info: they're using RedCarpet. We could use RedCarpet in MRI and kramdown in JRuby, but that's definitely a hack:

if RUBY_PLATFORM == 'java'
  spec.add_development_dependency 'kramdown'
else
  spec.add_development_dependency 'redcarpet'
end

(We'd also have to remove --markup-provider=kramdown from .yardopts. It'll just use whatever's available.)

I surveyed YARD's Markdown providers. BlueCloth, RDiscount, RedCarpet, and Ruby PEG Markdown all use C libraries behind the scenes, so they're out. That leaves kramdown, Maruku, and RDoc. Maruku doesn't support either fenced code block syntax, so it's out. RDoc appears to work reasonably well with the following caveats:

• It doesn't support tilde-fenced code blocks.
• It shows the badges as text links, which isn't a big deal for local documentation. ("Image links are not generated correctly")
• Code blocks are syntax highlighted in JRuby, but they lose indentation.

So between kramdown and RDoc, I think RDoc is the winner.