From: Joel VanderWerf <joelvanderwerf@...>
Date: 2010-04-20T04:59:19+09:00
Subject: Re: Documenting Rakefile using rdoc

Jean-Julien Fleck wrote:
> 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).

Maybe the best solution to your problem is by changing rake, not rdoc.

Regardless of what happens to rdoc, it would be nice if rake had some 
options for suppressing infrequently used targets, particularly ones in 
namespaces. The --tasks option isn't quite it:

     -T, --tasks [PATTERN]            Display the tasks (matching 
optional PATTERN) with descriptions, then exit.

This is great it you want to see *only* those tasks in some namespace 
(or with a specific file extension). But it would be nice if there were 
also something like

    --top-tasks                       Display only the top-level tasks 
(not in a namespace).

Then, you could put all your intermediate tasks in namespaces to hide 
them from end users.

In the meantime, you can define a little task to do it for you:

task "top-tasks" do
   `rake --tasks`.split("\n").each do |t|
     if t !~ /^rake \w+:/ and t =~ /^rake/
       puts t
     end
   end
end

Maybe you can even use Rake's API to get the task list without shelling out.