Documenting Rakefile using rdoc
in [Ruby]
|
From: Jean-Julien Fleck on 17 Apr 2010 03:34 Hello there, Does anybody know a gem that could be used to document a Rakefile the way rdoc does ? I've got a Rakefile full of tasks but only a few of them have a 'desc' keyword in order to keep 'rake -T' readable. I would like to have an html output of the list of all available tasks using the description given in the comments above each task, the same way rdoc does for the methods of a class. Is there an easy way to do it or special options to give to rdoc ? (a plain 'rdoc Rakefile' produce something that is unreadable) Thanks, -- JJ Fleck PCSI1 Lycée Kléber
From: Eric Hodel on 19 Apr 2010 03:57 On Apr 17, 2010, at 00:34, Jean-Julien Fleck wrote: > Does anybody know a gem that could be used to document a Rakefile the > way rdoc does ? > > I've got a Rakefile full of tasks but only a few of them have a 'desc' > keyword in order to keep 'rake -T' readable. I would like to have an > html output of the list of all available tasks using the description > given in the comments above each task, the same way rdoc does for the > methods of a class. Is there an easy way to do it or special options > to give to rdoc ? (a plain 'rdoc Rakefile' produce something that is > unreadable) I started on a Rakefile parser for RDoc but haven't finished it. Part of the problem is the rake tasks look bolted on to the side of RDoc. The other part of the problem is RDoc's Ruby parser is pretty crappy (if you want it to run in 1.8 and 1.9). Check it out: gem install rdoc-rake
From: Eric Hodel on 20 Apr 2010 02:57 On Apr 19, 2010, at 11:58, Jean-Julien Fleck wrote: > Hello Eric, > >> If it could come in handy why isn't it documented with a desc? > > Because my boss does not wish to :o) You should tell him what I said :) >> Hiding documentation behind a separate tool (rdoc-rake) that nobody knows about (just released yesterday) and mostly sucks (honestly, I only released it because you had an interest) is hostile to your users. > > What I would like to give to my (3) coworkers is a Rakefile (designed > to handle book's compilation in LaTeX and ensure all the data needed > to make the books have been gathered and up to date) and an online > documentation (using your tool for which I'm very grateful). They > would not have to compile the doc themselves. And the Rakefile has to > be concise with the tasks descriptions because the very last person to > use it (my boss) should be able to spot the right task to compile all > the books at once in the right format (even if the editing process the > intermediate tasks are very useful for us). Couldn't you make the default task do that so all he has to do is type "rake"? > I've documented all the tasks in the comments but opening the Rakefile > to read them is quite tedious and not really productive enough. > Knowing rdoc, I was just surprised nothing of the kind existed with > Rakefiles, hence my questions. > > Could you tell me where I should look in order to modify a bit > rdoc-rake to make it do what I want ? Right now rdoc-rake ignores comments, so you'd want to uncomment: http://github.com/drbrain/rdoc-rake/blob/master/lib/rdoc/parser/rake.rb#L257-258 and use that to add an extra block to gather up the TkCOMMENT nodes (you'll have to glue them together yourself). When you hit a non-comment node set the block to @desc. You can use RDoc::Text#normalize_comment to clean up the comment for you. Of course, there are tests to help move you along: http://github.com/drbrain/rdoc-rake/blob/master/test/test_rdoc_parser_rakerb I'd tell you to look at RDoc::Parser::Ruby to figure out how to gather up a comment, but it's really huge and ugly in there. (I think that code is in #parse_statements though.)
From: Robert Dober on 20 Apr 2010 04:34 On Tue, Apr 20, 2010 at 1:55 AM, Joel VanderWerf <joelvanderwerf(a)gmail.com> wrote: > namespace "tasks" do > rule /.*/ do |t| This is sooo cool, how come I never found this in the doc I needed it sooo badly. Cheers R. > pats = t.name.split(":")[1..-1].map {|pat| Regexp.new("\\A#{pat}\\z")} > Rake::Task.tasks.each do | tsk | > next unless tsk.full_comment > parts = tsk.name.split(":") > next unless parts.size <= pats.size + 1 > next unless pats.zip(parts).all? {|pat, part| pat === part} > printf "rake %-19s# %s\n", tsk.name, tsk.full_comment > end > end > end > > Use it like this: > > $ rake tasks # show all top level tasks > $ rake tasks:internals # show all tasks in "internals" namespace > $ rake tasks:internals:'build.*' # show all tasks in "internals" namespace > whose name begins with build > > It probably still needs some tinkering... > > -- The best way to predict the future is to invent it. -- Alan Kay
From: Jean-Julien Fleck on 19 Apr 2010 10:11
Hello Eric, > Check it out: > > gem install rdoc-rake Thanks, it's at least a beginning and make the code appear easily but would it be possible to have a Rakefile like this: *********** ## # Undescribed task that could come in handy and with comments that should be # included in rdoc task :undescribed puts "Doing some stuff" end ## # Described task so that rake -T works desc "Described task" task :described puts "Doing some other stuff" end *********** And make the comment appear in the doc and not only the one in the 'desc' attribute ? Thanks, -- JJ Fleck PCSI1 Lycée Kléber |