Rdoc exasperations - could use a little help

Ruby
1

I’ve recently restructured my current project per the recommendations in
Pickaxe 3rd edition. I can no no longer get rdoc to do its thing. When
all my code was in a single *.rb file in project root, I had no
problems. What I want is an rdoc /doc file in generated in project root.
Is not happening.

I’m running Ruby 1.8.7, using rdoc 2.3.0

  • project dir: …/setnet
  • launch dir: …/setnet/bin
  • class dir: …/setnet/lib/setnet <- all classes are in module SN.rb;
    there nothing else in this dir.
  • YAML db dir: …/setnet/db

CLI rdoc command I’m using:

rdoc -U -x /db /lib/setnet

Explanation: I want it to avoid the /db dir, because for some reason
rdoc thinks it’s supposed to parse my *.yml files, and upon trying this
generates yards of output, and error. I don’t understand this. Since
when are *.yml file anything but data, and since when is rdoc interested
in THAT? It never did that when I just had them in root, next to my *.rb
file. I’m baffled by this.

So, I start this little demo with NO /setnet/doc dir, for reasons you’ll
see shortly.

The above CLI command produces: “No newer files.” Why? Doesn’t “-U” mean
“do it regardless”? The “rdoc -h” output says “-U,
–force-update Forces rdoc to scan all sources even if
newer than the flag file.” It’s not doing that at all.

So, I give in and fake an update to a source file that doesn’t need one,
just to get rdoc to do something. Meanwhile, on the last run, it
generated a …/setnet/doc dir, of course, so next I get this puzzler,
using the same CLI command:

“Directory doc already exists, but it looks like it
isn’t an RDoc directory. Because RDoc doesn’t want to risk
destroying any of your existing files, you’ll need to
specify a different output directory name (using the
–op option).”

It can’t recognize it’s own output? I’ve never seen rdoc act like this
before.

OK. Start over. Fake another update. Delete the /doc file. Result:

“No newer files.”

Huh?

This has been going on for over an hour - a huge time waster, so far,
with no results at all, and I have no idea what to do. I’m somehow not
understanding SOMETHING, but…

Any help would be appreciated!

Tom

–

Tom C., MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< [email protected] >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)
2

rdoc -U -x /db /lib/setnet

IIRC you use linux. In that case a path starting with a slash denotes
an absolute path. Try: ls /

You might want to use:

cd setnet
rdoc -U -x db lib/setnet

Anyway, if you create a new project, I’d suggest to use a tool like
sow (in the hoe package), bones or something similar. Those tools also
create a Rakefile that does all those things with only minor
intervention.

3

Tom L. wrote:

Anyway, if you create a new project, I’d suggest to use a tool like
sow (in the hoe package), bones or something similar. Those tools also
create a Rakefile that does all those things with only minor
intervention.

Well, that’s an interesting notion. I know of those tools, but didn’t
think of using them. It would add to my learning (and hopefully decrease
my exasperation). And thanks for the absolute/relative distinction in
Linux path names. I hadn’t really grasped that yet.

Very helpful!

Tom

–

Tom C., MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< [email protected] >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)
4

On Feb 22, 2009, at 05:03, Tom C. wrote:

“Directory doc already exists, but it looks like it
isn’t an RDoc directory. Because RDoc doesn’t want to risk
destroying any of your existing files, you’ll need to
specify a different output directory name (using the
–op option).”

It can’t recognize it’s own output? I’ve never seen rdoc act like
this before.

RDoc doesn’t write out the file tagging the directory it generated
until the end, this is probably a bug.

OK. Start over. Fake another update. Delete the /doc file. Result:

“No newer files.”

I’ve only gotten this to reproduce when I have a doc dir.

5

Eric H. wrote:

RDoc doesn’t write out the file tagging the directory it generated
until the end, this is probably a bug.

OK. Start over. Fake another update. Delete the /doc file. Result:

“No newer files.”

I’ve only gotten this to reproduce when I have a doc dir.

Thanks for looking at this, Eric. I simply haven’t had a moment to
return to this problem, but hope to, in the days ahead. You’ve always
been an absolute model maintainer, in my eyes, so I’m sure that if
something needs attending too relative to these problems, you take care
of it. Most of the time I’m just tripping over my own feet and haven’t
yet figured that out!

t.

–

Tom C., MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< [email protected] >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)