Rdoc exasperations - could use a little help

ruby-talk
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 <dir> 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 Cloyd, MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (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

"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 <dir> 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.

···

On Feb 22, 2009, at 05:03, Tom Cloyd wrote:

4

Tom Link wrote:

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.

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 Cloyd, MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website) << sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

5

Eric Hodel 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 <dir> 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.

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.

···

On Feb 22, 2009, at 05:03, Tom Cloyd wrote:

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website) << sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~