how do I process a readme file with rdoc to display ruby script help/usage info

Question

I'd like to keep my usage documenation in a readme file (duh) instead of comments at the top of my script. How do I get RDoc::usage to pull the usage information out of the readme instead of the script comments?

Answer 1

RDoc is designed to parse a source file, look at the comments and their locations, build cross-references of the variables, and, when done, tie it all into a decent output. Because RDoc is designed to work against source files it might not be the best choice for what you want to do.

Instead you might want to look into Yard, which is tag-based. Can I get my README.textile into my RDoc with proper formatting? has some useful information for you too.

In either case, if you can't get the app to parse a README-type doc like you want, you might be able to spoof it by putting all your docs in the file, along with class and method stubs so the parsers can grab the parameters, globals, and other "whatnot" they need to create usable documentation.

Otherwise, you'll probably have to forgo using the automated help and type it all in.

My recommendation is to do it the RDoc way, and document inside your code. It's not hard to do at all, and the output can be very satisfactory. It's pretty amazing how good a job RDoc can do.

Answer 2

I'm certainly not experienced enough to tell you the answer, but please allow me one piece of advice.

Most of the developers are unlikely to ever update the documentation even if it's 3 lines of code above the implementation.

Do a favor and don't make the process even harder.

Keeping general documentation separate is a nice idea though, but it has nothing to do in your RDoc-generated output anyway.