rdoc overrides other markups unless explicitly unset on command line or in options.yml

[mattkimmel]

There is an issue where, when running mine, the markup always ends up set to :rdoc regardless of what's specified on the command line or in options.yml, unless the rdoc option is explicitly set to false with --no-rdoc on the command line or rdoc: false in options.yml.

With this fix, rdoc is disabled if another markup is specified, but remains the default if no markup is specified.

[benhamill]

I don't understand the code super well, but I noticed there's a weirdness with the --rdoc concept: It seems to be used both for readme/changelog format as well as to do with the format of documentation within the code.

From the ore README:

Markup

Ore supports RDoc, Markdown and Textile markup.

   $ mine my-project [--rdoc | --markdown | --textile]

Documentation

Ore supports generating projects with RDoc or YARD documentation.

   $ mine my-project [--rdoc | --yard]

What if you don't want to use YARD for your docs, but you want to use Markdown for your readme? Does this pull request enable that, or does it mean that you end up not specifying a documentation format if you specify a non-rdoc markup format?

[mattkimmel]

Unfortunately, I don't understand the code that well either, so this is just a stopgap fix. It makes mine --markdown equivalent to mine --no-rdoc --markdown, so you'll get a markdown readme and changelog, but no doc system. I don't see an existing code path that would get you rdoc documentation and a markdown/textile readme; maybe that's something better left to someone who understands the code better (or maybe I need to find some more time studying the problem).

[postmodern]

Yeah, the reason for this is that YARD also supports processing RDoc formatted documentation. To make matters more confusing, the next major version of RDoc will support Markdown formatted documentation (about time!).

[postmodern]

Confirmed that the currently version of rdoc will skip *.md, *.tt files. Not sure if it's a good idea to have generated documentation with no README/ChangeLog?

[postmodern]

Full Disclosure: I'm a strong believer that all projects should have some form of generated documentation. If you don't want to use RDoc, maybe use --yard instead?

[mattkimmel]

I agree about generated documentation. My hope was to be able to generate READMEs and ChangeLogs that are a bit more idiomatic and flexible (e.g. using GitHub Flavored Markdown), but I don't want to trade the ability to generate documentation for that. Maybe it would be worth decoupling the markup for top-level files from generated documentation?

On the other hand, maybe YARD is the best option for this. I haven't tried it, but I'll certainly take a look at it.

[postmodern]

When RDoc supports parsing markdown, I will remove the markup variable from the rdoc template.