Forum: Ruby rdoc exasperations - could use a little help

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Tom C. (Guest)
on 2009-02-22 15:04
(Received via mailing list)
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 C., MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< removed_email_address@domain.invalid >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom L. (Guest)
on 2009-02-22 15:53
(Received via mailing list)
> 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.
Tom C. (Guest)
on 2009-02-22 16:29
(Received via mailing list)
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
<< removed_email_address@domain.invalid >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Eric H. (Guest)
on 2009-02-25 19:20
(Received via mailing list)
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 <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.
Tom C. (Guest)
on 2009-02-26 01:24
(Received via mailing list)
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
<< removed_email_address@domain.invalid >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This topic is locked and can not be replied to.