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

[Eric Hodel]

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

My concern is for the loss of the sidebars. While I know frames are =20=

out
of fashion, having a sidebar was very convenient. Where as scrolling =20=

to
the bottom of a page is not.

I'm confused, the default RDoc template never had a sidebar. If you =20
don't want to scroll so far down the class list, use the search at the =20=

top.

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.

Go for it! RDoc will now automatically load other gems if they have =20
an rdoc/discover.rb. Load your extra template or what-have-you from =20
there and it'll be used automatically by RDoc.

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

I'm not sure how easy that is to add to Darkfish, but you're welcome =20
to try. I decided to release RDoc in its current state because it was =20=

good enough. It's easy to add templates to the old HTML generator, =20
look at rdoc_html_templates for inspiration.=

 

[Eric Hodel]

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

I'll fix this, either these files shouldn't show up (RDoc bug) or
a .document file is missing that should exclude these files (my
oversight). I made RDoc attempt to pull in more files, but I think it
is overzealous now.

There should only be three files in that list, all .txt files.

 

[Eric Hodel]

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.

more -t and vim -t work very well for me...

Navigating via a web browser across various files quickly gets
tedious. It's a breeze with a decent editor (one that has tags
support).

 

[Martin DeMello]

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)

I've filed a bug for this

martin

 

[Thomas Sawyer]

It definitely looks better.



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

Right. I see. It's on the class pages, but not on the main page.

I can understand that for people who don't bother to make their own
custom webpage for a project, but I almost always do. So for me the
normal rendering of README.txt makes more sense
(http://rdoc.rubyforge.org/README.txt.html). Not sure what the answer
is, maybe a new command line flag.

T.

 

[Clifford Heath]

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

Done. I wasn't familiar enough with RDoc to be sure it was a bug,
hence my posting here. Thanks!

Clifford Heath.

 

[Eric Hodel]

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

I'll fix this, either these files shouldn't show up (RDoc bug) or
a .document file is missing that should exclude these files (my
oversight). I made RDoc attempt to pull in more files, but I think
it is overzealous now.

There should only be three files in that list, all .txt files

Actually, it's a Hoe issue. I'll have fixed documentation up when I'm
next at a shell

 

[Eric Hodel]

Done. I wasn't familiar enough with RDoc to be sure it was a bug,
hence my posting here. Thanks!

If you think it could possibly be a bug, best to file it!

That's my rule.

 

[Roger Pack]

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/

I do like how the new sample looks.
I also do like a few things from the "old way" as well that I miss
slightly
: the method index, and the graphviz class tree.

[i.e. from http://rdoc.sourceforge.net/doc/index.html]

Was there a reason they were excluded?

Thanks for your work.
-=r

 

[Stefano Crocco]

Alle Thursday 29 January 2009, Eric Hodel ha scritto:

This release of RDoc brings some big changes. Most notably Michael
Granger=EF=BF=BDs 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=EF=BF=BDt plan to mak= e 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.

Very well done! I'm glad that at last we can have rdoc documentation withou=
t=20
frames.

The only thing I don't like is the default style sheet, both because I find=
=20
the green upon gray unpleasant and because the default font looks horrible =
in=20
my browser. This leads to the following question:=20

does the darkfish generator use the custom style sheet passed by the user=20
using the --style command line option? If so, either I'm doing something wr=
ong=20
or there's a bug. I tried the following command:

rdoc --style=3Dmy_rdoc.css *.rb

thinking that it would produce documentation using the my_rdoc.css style sh=
eet=20
instead of the default one. Instead, the documentation still used the defau=
lt=20
one. I also tried variants of the above command (for example using -s or=20
without the =3D or giving the full path of my_rdoc.css), but with the same=
=20
results. Am I missing something, is it a bug or by design the darkfish=20
generator doesn't take into account the --style option (in which case I thi=
nk=20
the documentation for the option should mention it)?

Thanks

Stefano

 

[Michael Granger]

does the darkfish generator use the custom style sheet passed by the
user
using the --style command line option? If so, either I'm doing
something wrong
or there's a bug. I tried the following command:

rdoc --style=my_rdoc.css *.rb

thinking that it would produce documentation using the my_rdoc.css
style sheet
instead of the default one. Instead, the documentation still used
the default
one.

That's my fault -- I hard-coded the path in the templates. I've added
a ticket to my tracker for this:

http://deveiate.org/projects/Darkfish-Rdoc/ticket/7

and I'll look at fixing it this weekend (at least for the darkfish-
rdoc gem).

 

[Eric Hodel]

This release of RDoc brings some big changes. Most notably Michael
Granger=EF=BF=BDs Darkfish generator has become the default output = format =20
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/

I do like how the new sample looks.
I also do like a few things from the "old way" as well that I miss
slightly
: the method index, and the graphviz class tree.

[i.e. from http://rdoc.sourceforge.net/doc/index.html]

Was there a reason they were excluded?

I restored a method index from the main page in RDoc 2.4.

Diagram generation is currently disabled because it needs vast =20
improvements and was pretty but otherwise mostly useless (I really =20
like it but have never actually used it).=

 

[Roger Pack]

I restored a method index from the main page in RDoc 2.4.

Diagram generation is currently disabled because it needs vast
improvements and was pretty but otherwise mostly useless (I really
like it but have never actually used it).

Thanks for doing that.
As a note the links to the files, i.e. "README.txt"
on
http://rdoc.rubyforge.org/RDoc/RDoc.html#M000417
result in 404's currently.
Thanks!
-=r

 

[Eric Hodel]

Thanks for doing that.
As a note the links to the files, i.e. "README.txt"
on
http://rdoc.rubyforge.org/RDoc/RDoc.html#M000417

Not for me:

$ curl -I http://rdoc.rubyforge.org/RDoc/RDoc.html#M000417
HTTP/1.1 200 OK
Date: Thu, 26 Feb 2009 00:55:42 GMT
Server: Apache
Last-Modified: Wed, 25 Feb 2009 05:59:15 GMT
ETag: "cf2f-463b7ef7db2c0"
Accept-Ranges: bytes
Content-Length: 53039
Vary: Accept-Encoding
Content-Type: text/html

 

[matt neuburg]

Not for me:

$ curl -I http://rdoc.rubyforge.org/RDoc/RDoc.html#M000417
HTTP/1.1 200 OK
Date: Thu, 26 Feb 2009 00:55:42 GMT
Server: Apache
Last-Modified: Wed, 25 Feb 2009 05:59:15 GMT
ETag: "cf2f-463b7ef7db2c0"
Accept-Ranges: bytes
Content-Length: 53039
Vary: Accept-Encoding
Content-Type: text/html

You didn't read what he said. He said that on that page are links to
README.txt and other files, and those links are duds. m.

 

[Eric Hodel]

You didn't read what he said. He said that on that page are links to
README.txt and other files, and those links are duds. m.

ah, oops! fixed, RDoc 2.4.1 forthcoming shortly.

 

[Roger Pack]

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

Now that I think about it, including the source of C methods which have
no documentation would also be quite helpful--in that case it basically
is the only documentation you get [ex: shoes].
Thanks!
-=r

 

[Roger Pack]

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:

I like darkfish. Thought I'd pipe in a couple suggestions.

1) the method names include a prefix '#'
which makes single letter method names hard to read

2) the font is low contrast so harder to read.

Just talking out loud.
=r

 

[Tom Cloyd]

I like darkfish. Thought I'd pipe in a couple suggestions.

1) the method names include a prefix '#'
which makes single letter method names hard to read

2) the font is low contrast so harder to read.

Just talking out loud.
=r

I totally concur about the low contrast fonts. Accessibility gurus say
DON'T DO THIS.

People with aging eyes - like me - find these fonts significantly harder
to read. People with genuine vision impairments find them simply
impossible, often.

Iron rule: if you put something on a website which people are expected
to read, make it black font against a light background. Large fonts can
be reverse-color - IF distinctly large AND well contrasted with a dark
back ground. This is a basic design aspect of webpages (or CSS sheets)
which MUST be attended to if usability matters to anyone 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)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~