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
···
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)
If it could come in handy why isn't it documented with a desc?
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.
···
On Apr 19, 2010, at 07:11, Jean-Julien Fleck wrote:
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 ?
If it could come in handy why isn't it documented with a desc?
Because my boss does not wish to :o)
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).
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 ?
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.
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:
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:
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.)
···
On Apr 19, 2010, at 11:58, Jean-Julien Fleck wrote:
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.
task ":top-tasks" do
Rake::Task.tasks.each do | tsk |
next if tsk.name =~ / # this could be more elaborate I guess
puts "#{tsk.name} #{tsk.full_comment}"
end
end
use with
rake :top-tasks ( just to distinguish from "normal" tasks ) I am too
lazy to tweak the rake script to allow
rake --top-tasks.
HTH
Robert
···
On Mon, Apr 19, 2010 at 9:59 PM, Joel VanderWerf <joelvanderwerf@gmail.com> wrote:
--
The best way to predict the future is to invent it.
-- Alan Kay
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.
task ":top-tasks" do
Rake::Task.tasks.each do | tsk |
next if tsk.name =~ / # this could be more elaborate I guess
puts "#{tsk.name} #{tsk.full_comment}"
end
end
use with
rake :top-tasks ( just to distinguish from "normal" tasks ) I am too
lazy to tweak the rake script to allow
rake --top-tasks.
Thanks, Robert!
Actually, I like
rake top-tasks
better than
rake --top-tasks
anyway.
It might be better to skip the tasks that have no desc:
task "top-tasks" do
Rake::Task.tasks.each do | tsk |
next if tsk.name =~ / or not tsk.full_comment
puts "#{tsk.name} #{tsk.full_comment}"
end
end
···
On Mon, Apr 19, 2010 at 9:59 PM, Joel VanderWerf > <joelvanderwerf@gmail.com> wrote:
task "tasks" do
Rake::Task.tasks.each do | tsk |
next if tsk.name =~ / or not tsk.full_comment
printf "rake %-19s# %s\n", tsk.name, tsk.full_comment
end
end
namespace "tasks" do
rule /.*/ do |t|
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
This is sooo cool, how come I never found this in the doc I needed it
sooo badly.
Cheers
R.
···
On Tue, Apr 20, 2010 at 1:55 AM, Joel VanderWerf <joelvanderwerf@gmail.com> wrote:
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
# this could be more elaborate I guess
or not tsk.full_comment