Documenting Rakefile using rdoc

[Jean-Julien Fleck]

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,

--=20
JJ Fleck
PCSI1 Lyc=E9e Kl=E9ber

 

[Eric Hodel]

Does anybody know a gem that could be used to document a Rakefile the
way rdoc does ?
=20
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

 

[Jean-Julien Fleck]

Hello Eric,

Check it out:

=A0gem 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 b=
e
# 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,

--=20
JJ Fleck
PCSI1 Lyc=E9e Kl=E9ber

 

[Eric Hodel]

Hello Eric,
=20
=20
Thanks, it's at least a beginning and make the code appear easily but
would it be possible to have a Rakefile like this:
=20
***********
##
# Undescribed task that could come in handy and with comments that = should be
# included in rdoc
=20
task :undescribed
puts "Doing some stuff"
end
=20
##
# Described task so that rake -T works
=20
desc "Described task"
task :described
puts "Doing some other stuff"
end
=20
***********
=20
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?

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.=

 

[Jean-Julien Fleck]

Hello Eric,

If it could come in handy why isn't it documented with a desc?

Because my boss does not wish to )

Hiding documentation behind a separate tool (rdoc-rake) that nobody knows=

about (just released yesterday) and mostly sucks (honestly, I only release=
d 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 ?

Cheers,

--=20
JJ Fleck
PCSI1 Lyc=E9e Kl=E9ber

 

[Joel VanderWerf]

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.

 

[Robert Dober]

On Mon, Apr 19, 2010 at 9:59 PM, Joel VanderWerf

task "top-tasks" do
=A0`rake --tasks`.split("\n").each do |t|
=A0 =A0if t !~ /^rake \w+:/ and t =3D~ /^rake/
=A0 =A0 =A0puts t
=A0 =A0end
=A0end
end

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

task ":top-tasks" do
Rake::Task.tasks.each do | tsk |
next if tsk.name =3D~ /:/ # 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


--=20
The best way to predict the future is to invent it.
-- Alan Kay

 

[Joel VanderWerf]

On Mon, Apr 19, 2010 at 9:59 PM, Joel VanderWerf

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

 

[Joel VanderWerf]

Here's another version:

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

It probably still needs some tinkering...

 

[Eric Hodel]

Hello Eric,
=20
=20
Because my boss does not wish to )

You should tell him what I said
knows about (just released yesterday) and mostly sucks (honestly, I only =
released it because you had an interest) is hostile to your users.

=20
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.
=20
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#L2=
57-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_rake=
rb

I'd tell you to look at RDoc:arser::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.)

 

[Robert Dober]

namespace "tasks" do
=A0rule /.*/ do |t|

This is sooo cool, how come I never found this in the doc I needed it
sooo badly.
Cheers
R.

=A0 =A0pats =3D t.name.split(":")[1..-1].map {|pat| Regexp.new("\\A#{pat}= \\z")}
=A0 =A0Rake::Task.tasks.each do | tsk |
=A0 =A0 =A0next unless tsk.full_comment
=A0 =A0 =A0parts =3D tsk.name.split(":")
=A0 =A0 =A0next unless parts.size <=3D pats.size + 1
=A0 =A0 =A0next unless pats.zip(parts).all? {|pat, part| pat =3D=3D=3D pa= rt}
=A0 =A0 =A0printf "rake %-19s# %s\n", tsk.name, tsk.full_comment
=A0 =A0end
=A0end
end

Use it like this:

$ rake tasks =A0# show all top level tasks
$ rake tasks:internals =A0# show all tasks in "internals" namespace
$ rake tasks:internals:'build.*' # show all tasks in "internals" namespac= e
whose name begins with build

It probably still needs some tinkering...

--=20
The best way to predict the future is to invent it.
-- Alan Kay