Take the 2-minute tour ×

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?

share|improve this question

2 Answers 2

up vote 1 down vote accepted

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.

share|improve this answer
Yeah, after having a closer look at the source, I see that it doesn't quite work how I thought it might. And on second thought, keeping it in the source might be fine afterall (i was thinking the readme might be easier to spot than finding the correct script in in the bin subdirectory of the package, but probably only marginally so). –  fakeleft Nov 29 '10 at 11:10
I think those are the same arguments that lead to RDoc in the first place. I find that it's a pain trying to manage separate doc files, but it's no big deal to document inline, especially when RDoc can pick those out and turn them into some usable files. Do take a look at Yard though. I saw some comments from another page where someone was using it for their docs via a separate file. –  the Tin Man Nov 29 '10 at 15:19

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.

share|improve this answer

Your Answer


