# Rdoc exasperations - could use a little help

**URL:** <https://www.ruby-forum.com/t/rdoc-exasperations-could-use-a-little-help/161027>\
**Category:** Ruby\
**Created:** [February 22, 2009, 2:04pm UTC](https://www.ruby-forum.com/t/rdoc-exasperations-could-use-a-little-help/161027 "2009-02-22T14:04:52Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![tbcox23](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/b9bd4f/32.png) [@tbcox23](https://www.ruby-forum.com/u/tbcox23)\
**Post date:** [February 22, 2009, 2:04pm UTC](https://www.ruby-forum.com/t/rdoc-exasperations-could-use-a-little-help/161027/1 "2009-02-22T14:04:52Z")

</div>

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

–

```auto
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)

```

---

<div class="post-metadata">

**Author:** ![tbcox23](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/b9bd4f/32.png) [@tbcox23](https://www.ruby-forum.com/u/tbcox23)\
**Post date:** [February 22, 2009, 2:53pm UTC](https://www.ruby-forum.com/t/rdoc-exasperations-could-use-a-little-help/161027/2 "2009-02-22T14:53:29Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![tbcox23](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/b9bd4f/32.png) [@tbcox23](https://www.ruby-forum.com/u/tbcox23)\
**Post date:** [February 22, 2009, 3:29pm UTC](https://www.ruby-forum.com/t/rdoc-exasperations-could-use-a-little-help/161027/3 "2009-02-22T15:29:16Z")

</div>

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

–

```auto
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)

```

---

<div class="post-metadata">

**Author:** ![tbcox23](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/b9bd4f/32.png) [@tbcox23](https://www.ruby-forum.com/u/tbcox23)\
**Post date:** [February 25, 2009, 6:20pm UTC](https://www.ruby-forum.com/t/rdoc-exasperations-could-use-a-little-help/161027/4 "2009-02-25T18:20:45Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![tbcox23](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/b9bd4f/32.png) [@tbcox23](https://www.ruby-forum.com/u/tbcox23)\
**Post date:** [February 26, 2009, 12:24am UTC](https://www.ruby-forum.com/t/rdoc-exasperations-could-use-a-little-help/161027/5 "2009-02-26T00:24:06Z")

</div>

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.

–

```auto
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)

```