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:
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.
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:
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?
···
--
vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407
On Thu, Jan 29, 2009 at 10:23 AM, Eric Hodel <drbrain@segment7.net> 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:
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
···
On Thu, Jan 29, 2009 at 6:53 AM, Eric Hodel <drbrain@segment7.net> 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:
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.
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:
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?
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 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.
Alle Thursday 29 January 2009, Eric Hodel ha scritto:
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:
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.
Very well done! I'm glad that at last we can have rdoc documentation without
frames.
The only thing I don't like is the default style sheet, both because I find
the green upon gray unpleasant and because the default font looks horrible in
my browser. This leads to the following question:
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. I also tried variants of the above command (for example using -s or
without the = or giving the full path of my_rdoc.css), but with the same
results. Am I missing something, is it a bug or by design the darkfish
generator doesn't take into account the --style option (in which case I think
the documentation for the option should mention it)?
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
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:
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.
On Jan 29, 2009, at 3:24, Martin DeMello <martindemello@gmail.com> wrote:
On Thu, Jan 29, 2009 at 6:53 AM, Eric Hodel <drbrain@segment7.net> > 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:
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.
On Jan 30, 2009, at 03:27 AM, Clifford Heath wrote:
Eric Hodel 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.
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:
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.
(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.
I'm confused, the default RDoc template never had a sidebar. If you don't want to scroll so far down the class list, use the search at the top.
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.
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 an rdoc/discover.rb. Load your extra template or what-have-you from 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 to try. I decided to release RDoc in its current state because it was good enough. It's easy to add templates to the old HTML generator, look at rdoc_html_templates for inspiration.
···
On Jan 30, 2009, at 05:18 AM, Thomas Sawyer wrote:
and I'll look at fixing it this weekend (at least for the darkfish-rdoc gem).
···
On Feb 3, 2009, at 7:36 AM, Stefano Crocco wrote:
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.
--
Michael Granger <ged@FaerieMUD.org>
Rubymage, Architect, Believer
The FaerieMUD Consortium <http://www.FaerieMUD.org/>
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).
···
On Feb 2, 2009, at 06:29, Roger Pack wrote:
Eric Hodel 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:
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.
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
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
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website) << sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Will sift rubyforge for candidates. Prawn looks pretty good in terms
of coverage, though perhaps something smaller would be better.
martin
···
On Thu, Jan 29, 2009 at 9:14 PM, Eric Hodel <drbrain@segment7.net> wrote:
On Jan 29, 2009, at 3:24, Martin DeMello <martindemello@gmail.com> 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.
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.
···
On Jan 30, 2009, at 5:27 AM, Clifford Heath wrote:
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.]