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.
on 2009-01-29 02:25
on 2009-01-29 04:33
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: > > 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?
on 2009-01-29 04:46
Joel VanderWerf 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: >> >> 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.
on 2009-01-29 05:51
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: > > 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
on 2009-01-29 13:09
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: > > 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
on 2009-01-29 16:47
On Jan 29, 2009, at 3:24, Martin DeMello <martindemello@gmail.com> 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
on 2009-01-29 17:31
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. > > Patches welcome Will sift rubyforge for candidates. Prawn looks pretty good in terms of coverage, though perhaps something smaller would be better. martin
on 2009-01-29 19:05
On Thu, Jan 29, 2009 at 11:28 AM, Martin DeMello
<martindemello@gmail.com> 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
on 2009-01-30 04:32
On Jan 29, 2009, at 10:02 AM, Gregory Brown 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
on 2009-01-30 12:30
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.
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 Heath.
on 2009-01-30 14:21
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: > > 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.
on 2009-01-30 14:40
On Jan 30, 2009, at 5:27 AM, Clifford Heath 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 Gray II
on 2009-01-30 15:36
James Gray wrote: > On Jan 30, 2009, at 5:27 AM, Clifford Heath 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.
on 2009-01-30 15:39
On Fri, Jan 30, 2009 at 9:33 AM, Thomas Sawyer <transfire@gmail.com> 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
on 2009-01-30 15:44
On Jan 30, 2009, at 8:36 AM, Gregory Brown wrote:
> Oh, that's a very interesting thought. +1
Yeah, I agree. That would be nice.
James Edward Gray II
on 2009-01-30 16:54
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 Gray 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
on 2009-01-30 16:56
>> 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
on 2009-01-30 21:01
On Jan 30, 2009, at 5:37, James Gray <james@grayproductions.net> wrote: > On Jan 30, 2009, at 5:27 AM, Clifford Heath 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
on 2009-01-30 22:08
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
on 2009-01-30 22:34
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. If you don't file a bug it won't get fixed.
on 2009-01-30 22:44
On Jan 30, 2009, at 05:18 AM, Thomas Sawyer wrote: >> released separately as unmaintained software. I don�t plan to make > 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 2009-01-30 22:49
On Jan 30, 2009, at 07:51 AM, Roger Pack wrote: > 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.
on 2009-01-30 22:52
On Jan 30, 2009, at 06:33 AM, Thomas Sawyer 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. 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).
on 2009-01-30 23:03
2009/1/31 Rados³aw Bu³at <radek.bulat@gmail.com>: > 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
on 2009-01-30 23:07
Roger Pack wrote: > 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 Gray II > > > +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.
on 2009-01-31 06:41
On Jan 30, 2009, at 13:46, Eric Hodel <drbrain@segment7.net> wrote: > 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
on 2009-01-31 08:00
Eric Hodel wrote: > On Jan 30, 2009, at 03:27 AM, Clifford Heath wrote: >> Has the behavior of #:nodoc: changed? > 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.
on 2009-01-31 22:06
On Jan 30, 2009, at 23:00 PM, Clifford Heath wrote: > Eric Hodel wrote: >> On Jan 30, 2009, at 03:27 AM, Clifford Heath wrote: >>> Has the behavior of #:nodoc: changed? >> 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! If you think it could possibly be a bug, best to file it! That's my rule.
on 2009-02-02 15:29
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: > > 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
on 2009-02-03 16:37
Alle Thursday 29 January 2009, Eric Hodel ha scritto: > 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)? Thanks Stefano
on 2009-02-07 02:32
On Feb 3, 2009, at 7:36 AM, Stefano Crocco wrote: > 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).
on 2009-02-25 20:52
On Feb 2, 2009, at 06:29, Roger Pack wrote: > 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 improvements and was pretty but otherwise mostly useless (I really like it but have never actually used it).
on 2009-02-25 23:28
> > 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
on 2009-02-26 01:58
On Feb 25, 2009, at 14:27, Roger Pack wrote: >> 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 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
on 2009-02-26 02:32
Eric Hodel <drbrain@segment7.net> wrote: > > http://rdoc.rubyforge.org/RDoc/RDoc.html#M000417 > 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.
on 2009-02-26 22:27
On Feb 25, 2009, at 17:30, matt neuburg wrote: >>> on >> 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. ah, oops! fixed, RDoc 2.4.1 forthcoming shortly.
on 2009-02-27 23:27
Roger Pack 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 > > +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
on 2009-07-04 00:44
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 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
on 2009-07-04 00:56
Roger Pack wrote: > 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) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Enable email notification
Enable multi-page viewPlease log in before posting. Registration is free and takes only a minute.
Existing account
(Switch to SSL-encrypted connection)
NEW: Do you have a Google/GoogleMail or Yahoo account? No registration required!
Log in with Google account | Log in with Yahoo account
Log in with Google account | Log in with Yahoo account
No account? Register here.