[Proposal] `bundle exec rdoc` command should work for rdoc itself

[okuramasafumi]

Problem

Currently, running bundle exec rdoc in the repository root causes the following error:

uh-oh! RDoc had a problem:

Directory doc already exists, but it looks like it isn't an RDoc directory.

Because RDoc doesn't want to risk destroying any of your existing files,
you'll need to specify a different output directory name (using the --op <dir>
option)


run with --debug for full backtrace

Solution

That seems caused by doc directory. Inside it there's rdoc/markup_reference.rb file only. While this file seems to be processed by Rakefile, it doesn't have to exist in doc directory since the file path is hardcoded. So moving rdoc/markup_reference.rb file into some other place should be enough.

[hsbt]

You can use rake rdoc, not rdoc for that.

[okuramasafumi]

@hsbt Thank you for the info. README says nothing about rake rdoc command, though, and it's weird to me that RDoc cannot run the command on README for itself. And doc/rdoc/markup_reference.rb doesn't make sense since that file is not a document. So I believe the change in #1125 worth it, although it might be hard to deal with ruby/ruby script issue.

[st0012]

I tend to agree with @okuramasafumi here. From the original PR that introduced the file (https://github.com/ruby/rdoc/pull/824), it doesn't look like it has to be under doc, just outside lib should be enough. And not being able to run rdoc easily from the repo means that contributors and maintainers will likely test it less often, and thus make it more prone to error in the long-term.

[hsbt]

I don't agree for that. We should use rake rdoc to generate documentation on this repository. Because rdoc need generated parser files now. So, rdoc command is not working standalone with fresh repository.