Rdoc run-time length question

I note that if I don’t delete the relevant /docs dir, then each time I
run rdoc on my ruby file it takes longer, and reports the involvement of
ever more files. Can someone explain this behavior? It’s dramatic how
much better (quicker) it runs if I delete the doc dir every time.

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)

Tom C. wrote:

I note that if I don’t delete the relevant /docs dir, then each time I
run rdoc on my ruby file it takes longer, and reports the involvement
of ever more files. Can someone explain this behavior? It’s dramatic
how much better (quicker) it runs if I delete the doc dir every time.

t.

A little documentation:

[email protected]:~/Ruby-work/setnet/lib/setnet$ ls
SN.rb <= a single module, containing 6 classes
[email protected]:~/Ruby-work/setnet/lib/setnet$ rdoc -N -U
Parsing sources with 2 thread(s)…
100% [ 1/ 1] SN.rb

Generating Darkfish…

Files: 1
Classes: 6
Modules: 1
Methods: 58
Elapsed: 7.3s

[email protected]:~/Ruby-work/setnet/lib/setnet$ rdoc -N -U <= immediate
rerun, after trivial file change
Parsing sources with 2 thread(s)…
100% [16/16] doc/index.html

Generating Darkfish…

Files: 16
Classes: 6
Modules: 1
Methods: 58
Elapsed: 17.4s
[email protected]:~/Ruby-work/setnet/lib/setnet$

As you can see, the file count and elapsed time doubles.

[email protected]:~/Ruby-work/setnet/lib/setnet$ rdoc -N -U
Parsing sources with 2 thread(s)…
Unrecognized directive ‘d’ in doc/doc/SN/SetNet_html.html <=???
100% [31/31] doc/index.html

Generating Darkfish…

Files: 31
Classes: 6
Modules: 1
Methods: 58
Elapsed: 39.2s
[email protected]:~/Ruby-work/setnet/lib/setnet$

File count and elapsed time just keeps doubling.

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)

Tom C. wrote:

Modules: 1
Files: 16
Unrecognized directive ‘d’ in doc/doc/SN/SetNet_html.html <=???

File count and elapsed time just keeps doubling.

t.

It’s processing the doc/ directory.

-Justin

Justin C. wrote:

A little documentation:
Classes: 6

Parsing sources with 2 thread(s)…
[email protected]:~/Ruby-work/setnet/lib/setnet$

I don’t understand - processing involves doubling the time and files.
This quickly becomes a monster. Why? Am I running this thing wrong? I
don’t see anything in the documentation about this (from “rdoc -h”). I’m
wondering what I don’t know here.

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)

Tom C. wrote:

Files: 1
Generating Darkfish…
[email protected]:~/Ruby-work/setnet/lib/setnet$ rdoc -N -U
Elapsed: 39.2s
-Justin

I don’t understand - processing involves doubling the time and files.
This quickly becomes a monster. Why? Am I running this thing wrong? I
don’t see anything in the documentation about this (from “rdoc -h”).
I’m wondering what I don’t know here.

t.

I would not say you are running it wrong (though I am far from an rdoc
master). The default behavior when you run rdoc is for it to parse all
files in the current directory and any subdirectories. Then it generates
the documentation and puts it in the doc/ directory.

Okay.

But when it does that, it also puts a copy of -everything- it parsed
into the doc/files/ directory.

Now you run rdoc again. This time, it parses and -copies- all the same
files it did before, -plus- everything in the doc/ directory. That means
all the documentation generated before gets copied and put into
doc/files/. Including the old doc/files/

You can try using --exclude doc/ so that it does not parse the doc/
directory.

I am still not sure that is clear…but I hope it helps a little bit?

-Justin

Followup on my last post: these rdoc run parameters also seem to have NO
effect:

-m NAME - “NAME will be the initial page displayed” <= nope. Has no
effect that I can see, at all.

-t TITLE - Set TITLE as the title for HTML output <= nope. Does nothing
that I can see.

Of the parameters I’ve tried, -x and -N work great. But not these
others.

???

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)

Justin C. wrote:

t.

Methods: 58

I would not say you are running it wrong (though I am far from an
files it did before, -plus- everything in the doc/ directory. That

Justin,

Thanks very much for the help.

  • Yes, the -x /doc parameter solves the run-time doubling problem.
    Thanks. I didn’t see that solution because I didn’t see what the problem
    really was, and your explanation of it was enlightening. However, the
    file copy does NOT go into /doc/files. Rdoc simply copies everything,
    including the current /doc dir into a NEW /doc dir, we that we get, over
    time /doc/doc/doc/doc/doc/doc/doc… And this is good for what?

Why in blazes would rdoc do this dumb thing - copying itself over and
over with each run? If there’s some purpose to it, why is it not
documented?

  • Also - the “-d” is worthless. Diagram generation via graphviz’s dot
    just isn’t available. I have graphviz installed (I’m running Kubuntu
    Linux 9.04) and have been using it for multiple projects. I’ve been all
    over the graphviz.org website, and there is NO separate “dot” download,
    as referred to in this section of the output from “rdoc -h”:

-d, --diagram Generate diagrams showing modules and classes. You need
dot V1.8.6 or later to
use the --diagram option correctly. Dot is available from
http://graphviz.org

One can only install the “graphviz” package, which I know includes
“dot”, 'cause I call it all the time. However, I can discover NO way to
make rdoc generate those diagrams referred to. Am I missing something?

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)

Tom C. wrote:

  • Also - the “-d” is worthless. Diagram generation via graphviz’s dot
    just isn’t available. I have graphviz installed (I’m running Kubuntu
    Linux 9.04) and have been using it for multiple projects. I’ve been all
    over the graphviz.org website, and there is NO separate “dot” download,
    as referred to in this section of the output from “rdoc -h”:

This used to work very nicely in the old framed rdoc template, and I’m
pretty sure I didn’t install dot separately from graphviz.

Somehow, dot worked when the rdoc example site was generated (2003!):

http://rdoc.sourceforge.net/doc/index.html

(click on a class in the middle pane to see a diagram). But it doesn’t
work for me now…

Joel VanderWerf wrote:

-t TITLE - Set TITLE as the title for HTML output <= nope. Does
nothing that I can see.

Are you sure? I get this:

    <title>FooStuff</title>

in the index.html, and it shows up as the title within the page and as
the window name in my browser, which is convenient.
Well, there’s more to the story! It actually does work - as you
describe, and as I’d expect, but only for one page: index.html. You can
get to that page only by browsing to it explicitly. Once you are on
another page, there’s no way to link back (ouch!). So, what you do NOT
get is a consistent string of something or other in your tag for
all pages, and that was what I expected and wanted, actually. So,
exactly how useful is this? Not very.

I get the same doc/doc/… problem as you do.

Thanks for the confirmation. I though maybe I was trapped in my own
private rdoc hell - the exact nature of which appeared to be not
documented at all!

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)

Tom C. wrote:

Followup on my last post: these rdoc run parameters also seem to have NO
effect:

-m NAME - “NAME will be the initial page displayed” <= nope. Has no
effect that I can see, at all.

It used to work, but maybe that was only with the older templates
(jamis.rb). For some reason, -T doesn’t let me select that one any more,
and the darkfish template is kinda unpleasant all around.

-t TITLE - Set TITLE as the title for HTML output <= nope. Does nothing
that I can see.

Are you sure? I get this:

     <title>FooStuff</title>

in the index.html, and it shows up as the title within the page and as
the window name in my browser, which is convenient.

I get the same doc/doc/… problem as you do.

On Jul 15, 2009, at 08:52, Tom C. wrote:

One can only install the “graphviz” package, which I know includes
“dot”, 'cause I call it all the time. However, I can discover NO way
to make rdoc generate those diagrams referred to. Am I missing
something?

Since darkfish, this feature hasn’t been restored. Until I get around
to it, I welcome your patch.

On Jul 15, 2009, at 09:05, Tom C. wrote:

others.
Unless you file a bug this won’t get fixed.

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs