rdoc run-time length question

[Tom Cloyd]

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

 

[Tom Cloyd]

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:

tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$ ls
SN.rb <= a single module, containing 6 classes
tomc@tomc-desktop:~/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

tomc@tomc-desktop:~/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
tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$

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

tomc@tomc-desktop:~/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
tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$

File count and elapsed time just keeps doubling.

t.

--

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

 

[Justin Collins]

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:

tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$ ls
SN.rb <= a single module, containing 6 classes
tomc@tomc-desktop:~/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

tomc@tomc-desktop:~/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
tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$

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

tomc@tomc-desktop:~/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
tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$

File count and elapsed time just keeps doubling.

t.

It's processing the doc/ directory.

-Justin

 

[Tom Cloyd]

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:

tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$ ls
SN.rb <= a single module, containing 6 classes
tomc@tomc-desktop:~/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

tomc@tomc-desktop:~/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
tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$

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

tomc@tomc-desktop:~/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
tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$

File count and elapsed time just keeps doubling.

t.

It's processing the doc/ directory.

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

--

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

 

[Justin Collins]

Tom Cloyd 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:

tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$ ls
SN.rb <= a single module, containing 6 classes
tomc@tomc-desktop:~/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

tomc@tomc-desktop:~/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
tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$

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

tomc@tomc-desktop:~/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
tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$

File count and elapsed time just keeps doubling.

t.

It's processing the doc/ directory.

-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

 

[Tom Cloyd]

Tom Cloyd wrote:
Tom Cloyd 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:

tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$ ls
SN.rb <= a single module, containing 6 classes
tomc@tomc-desktop:~/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

tomc@tomc-desktop:~/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
tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$

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

tomc@tomc-desktop:~/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
tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$

File count and elapsed time just keeps doubling.

t.



It's processing the doc/ directory.

-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

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

 

[Tom Cloyd]

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

 

[Joel VanderWerf]

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.

 

[Joel VanderWerf]

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

 

[Tom Cloyd]

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.


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

 

[Eric Hodel]

* 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?

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

 

[Eric Hodel]

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.

Unless you file a bug this won't get fixed.