RDoc 2.3 now with Darkfish, without CHM and extra HTML templates


#1

This release of RDoc brings some big changes. Most notably Michael
Granger’s Darkfish generator has become the default output format for
RDoc! Michael put a ton of great work into this, and it looks quite
lovely. Check out the RDoc documentation for a sample:

http://rdoc.rubyforge.org/

rdoc_chm and rdoc_html_templates have been split off from RDoc and
released separately as unmaintained software. I don’t plan to make any
future changes or updates to rdoc_html_templates (which are for the
old HTML generator) ever, but somebody may be interested in taking
over maintainership of the rdoc_chm generator.

rdoc will automatically detect rdoc_html_templates and rdoc_chm, so
you only need to install them to make them usable via command-line
options.


#2

Eric H. wrote:

This release of RDoc brings some big changes. Most notably Michael
Granger’s Darkfish generator has become the default output format for
RDoc! Michael put a ton of great work into this, and it looks quite
lovely. Check out the RDoc documentation for a sample:

http://rdoc.rubyforge.org/

It does look nice, except for source code display. The bg color is gray,
and so fg cyan/orange do not display well. Is this the default? Is it
changeable?


#3

Joel VanderWerf wrote:

Eric H. wrote:

This release of RDoc brings some big changes. Most notably Michael
Granger�s Darkfish generator has become the default output format for
RDoc! Michael put a ton of great work into this, and it looks quite
lovely. Check out the RDoc documentation for a sample:

http://rdoc.rubyforge.org/

It does look nice, except for source code display. The bg color is gray,
and so fg cyan/orange do not display well. Is this the default? Is it
changeable?

I appreciate the effort, it’s just the colors do seem odd. The
pea-green on top of the gray is difficult to read, and may even be
uglier than congressman Henry Waxman. Please consider changing the
default colors.


#4

On Thu, Jan 29, 2009 at 6:53 AM, Eric H. removed_email_address@domain.invalid
wrote:

This release of RDoc brings some big changes. Most notably Michael G.'s
Darkfish generator has become the default output format for RDoc! Michael
put a ton of great work into this, and it looks quite lovely. Check out the
RDoc documentation for a sample:

http://rdoc.rubyforge.org/

The RDoc documentation is a pretty bad sample, since the majority of
the methods say ‘not documented’. I suggest putting a small but
well-documented project on the site purely to act as a demo.

martin


#5

On Jan 29, 2009, at 3:24, Martin DeMello removed_email_address@domain.invalid
wrote:

http://rdoc.rubyforge.org/

The RDoc documentation is a pretty bad sample, since the majority of
the methods say ‘not documented’. I suggest putting a small but
well-documented project on the site purely to act as a demo.

Patches welcome


#6

On Thu, Jan 29, 2009 at 10:23 AM, Eric H. removed_email_address@domain.invalid
wrote:

This release of RDoc brings some big changes. Most notably Michael G.'s
Darkfish generator has become the default output format for RDoc! Michael
put a ton of great work into this, and it looks quite lovely. Check out the
RDoc documentation for a sample:

http://rdoc.rubyforge.org/

It has a nice validate link, but seems like it got errors:
http://validator.w3.org/check?uri=http%3A%2F%2Frdoc.rubyforge.org%2F

^ manveru


#7

On Thu, Jan 29, 2009 at 9:14 PM, Eric H. removed_email_address@domain.invalid
wrote:

On Jan 29, 2009, at 3:24, Martin DeMello removed_email_address@domain.invalid wrote:

The RDoc documentation is a pretty bad sample, since the majority of
the methods say ‘not documented’. I suggest putting a small but
well-documented project on the site purely to act as a demo.

Patches welcome

Will sift rubyforge for candidates. Prawn looks pretty good in terms
of coverage, though perhaps something smaller would be better.

martin


#8

On Jan 29, 2009, at 10:02 AM, Gregory B. wrote:

well-documented project on the site purely to act as a demo.
I’ll probably give the latest RDoc a try soon, and post here if I do.
Oh, you can rebuild all your rdoc on your machine with:

sudo gem rdoc --all --no-ri


#9

On Thu, Jan 29, 2009 at 11:28 AM, Martin DeMello
removed_email_address@domain.invalid wrote:

of coverage, though perhaps something smaller would be better.
Now that prawn has been split out into various extensions, prawn-core
isn’t too bad.
http://prawn.majesticseacreature.com/docs/prawn-core/

I’ll probably give the latest RDoc a try soon, and post here if I do.

-greg


#10

Eric H. wrote:

This release of RDoc brings some big changes.

Thanks, I think it’s an improvement. Still has a way to go IMO,
however…

Has the behavior of #:nodoc: changed? I have empty documentation
for classes where the class definition has #:nodoc:, instead of no
documentation… If this is a change, I think it’s an error.

I’d like to see the class index above the file index - I rarely find
the file index useful and almost always use the class index.

Clifford H…


#11

On Jan 30, 2009, at 5:27 AM, Clifford H. wrote:

I’d like to see the class index above the file index - I rarely find
the file index useful and almost always use the class index.

I whole heartedly agree with that.

James Edward G. II


#12

James G. wrote:

On Jan 30, 2009, at 5:27 AM, Clifford H. wrote:

I’d like to see the class index above the file index - I rarely find
the file index useful and almost always use the class index.

I whole heartedly agree with that.

How could anyone NOT agree? Since the file page often contains nothing.
And if it does contain anything it is usually redundant information.

I’ve been meaning to make this suggestion for a while now: Would it not
be more useful if the file page showed the entire file’s contents
verbatim? This is one thing that in my mind is missing from RDoc --a way
to look at the source in full.

T.


#13

Eric H. wrote:

This release of RDoc brings some big changes. Most notably Michael
Granger�s Darkfish generator has become the default output format for
RDoc! Michael put a ton of great work into this, and it looks quite
lovely. Check out the RDoc documentation for a sample:

http://rdoc.rubyforge.org/

rdoc_chm and rdoc_html_templates have been split off from RDoc and
released separately as unmaintained software. I don�t plan to make any
future changes or updates to rdoc_html_templates (which are for the
old HTML generator) ever, but somebody may be interested in taking
over maintainership of the rdoc_chm generator.

rdoc will automatically detect rdoc_html_templates and rdoc_chm, so
you only need to install them to make them usable via command-line
options.

(Sigh. the Google Group mirror is acting up again, so i will be replying
to this for the third time.)

My concern is for the loss of the sidebars. While I know frames are out
of fashion, having a sidebar was very convenient. Where as scrolling to
the bottom of a page is not.

Also, I think it would be nice if RDoc offered a few template options,
varying up the layout, suitable to variant preferences and/or project
needs, eg. small projects versus large ones.

Finally, what is the state of creating custom templates? Are we using
rhtml now? Is their a tutorial anywhere on the topic?

Thanks,
T.


#14

On Jan 30, 2009, at 8:36 AM, Gregory B. wrote:

Oh, that’s a very interesting thought. +1
Yeah, I agree. That would be nice.

James Edward G. II


#15

On Fri, Jan 30, 2009 at 9:33 AM, Thomas S. removed_email_address@domain.invalid
wrote:

I’ve been meaning to make this suggestion for a while now: Would it not
be more useful if the file page showed the entire file’s contents
verbatim? This is one thing that in my mind is missing from RDoc --a way
to look at the source in full.

Oh, that’s a very interesting thought. +1


#16

I’ve been meaning to make this suggestion for a while now: Would it not
be more useful if the file page showed the entire file’s contents
verbatim? This is one thing that in my mind is missing from RDoc --a way
to look at the source in full.

Oh, that’s a very interesting thought. +1

+1 for me.

Also a nice thought would be to be able to “open the full file” from the
code snippet pop-downs–like a link back to see that method within
context.

Thanks for helping out.
-=r


#17

On Jan 30, 2009, at 5:37, James G. removed_email_address@domain.invalid wrote:

On Jan 30, 2009, at 5:27 AM, Clifford H. wrote:

I’d like to see the class index above the file index - I rarely find
the file index useful and almost always use the class index.

I whole heartedly agree with that.

Try the quicksearch at the top of the class index


#18

It definitely looks better.

I’d like to see the class index above the file index - I rarely find
the file index useful and almost always use the class index.

I whole heartedly agree with that.

James Edward G. II

+1
I assume that’s referring to the leftmost side bars on pages like
http://rdoc.rubyforge.org/RDoc.html
?

I’d also tend to prefer the class index above the file index on the main
page [http://rdoc.rubyforge.org/], or the two side by side, at the
bottom.

also the links to files like a.png point [in error] to a.png.rhtml

And when you click on those files, it shows the requires and last
modified file dates–it would be way nice to display the file itself, as
well [or is it supposed to?]

Also a few suggestions:

the link color could darken a bit to get better contrast–they sometimes
are a little hard contrast-wise against the background [ex:
http://rdoc.rubyforge.org/ at the top, if you’ve never clicked on any of
the links.]

Thanks!
-=r


#19

On Jan 30, 2009, at 03:27 AM, Clifford H. wrote:

Eric H. wrote:

This release of RDoc brings some big changes.

Thanks, I think it’s an improvement. Still has a way to go IMO,
however…

Has the behavior of #:nodoc: changed? I have empty documentation
for classes where the class definition has #:nodoc:, instead of no
documentation… If this is a change, I think it’s an error.

If you don’t file a bug it won’t get fixed.


#20

The are many linked files that ends up with 404, for example:
page: http://rdoc.rubyforge.org/
section FILES: bullet_toggle_minus.png (I think that all .png files
does not work)


Pozdrawiam

Rados³aw Bu³at
http://radarek.jogger.pl - mój blog