RDoc 2.1.0

Eric Hodel | Mon, 21 Jul 2008 05:25:39 GMT

RDoc is an application that produces documentation for one or more Ruby source files. RDoc includes the `rdoc` and `ri` tools for generating and displaying online documentation.

At this point in time, RDoc 2.x is a work in progress and may incur further API changes beyond what has been made to the RDoc 1.0.1. Command-line tools are largely unaffected, but internal APIs may shift rapidly.

  • 3 Major Enhancements:
    • RDoc now knows about meta-programmed methods, see RDoc::Parser::Ruby
    • Reorganized parsers under RDoc::Parser base class
    • ri now walks the ancestors of a class looking for a method e.g. ri File#read displays documentation for IO#read (may require regeneration of ri data)
  • 5 Minor Enhancements:
    • Allow links to files
    • Default options now taken from RDOCOPT environment variable
    • Class method documentation can be found at toplevel now (def X.foo)
    • Allow HTML templates distributed as gems to be loaded with the -T option, just like the standard templates in rdoc/generator/html (so an HTML template lib/new_template.rb in a gem can be used with rdoc -T new_template)
    • `rdoc -v` prints out files, classes, modules and methods as it goes
  • 11 Bug Fixes:
    • `ri Foo.bar` now looks for class methods also
    • Sections work in the default template again
    • Doesn’t warn about :foo:: list item being an unrecognized directive
    • RDoc no longer converts characters inside tt tags
    • Fixed “unitialized constant RDoc::Markup::ToHtml::HTML”
    • Fixed generation of relative links
    • Fixed various diagram generation issues
    • Fixed templates broken by switch to erb
    • Fixed issue with <!- -> style comments
    • Lowercase words are no longer rdoc’d as methods without leading #, as described in the documentation
    • RDoc now correctly sets superclasses if they were originally unknown

Posted in ,  | no comments

RDoc 2.0.0

Eric Hodel | Fri, 11 Apr 2008 01:21:00 GMT

rdoc version 2.0.0 has been released!

http://rubyforge.org/projects/rdoc

http://rdoc.rubyforge.org/rdoc

RDoc is an application that produces documentation for one or more Ruby source files. RDoc includes the `rdoc` and `ri` tools for generating and displaying online documentation.

At this point in time, RDoc 2.x is a work in progress and may incur further API changes beyond what has been made to the RDoc 1.0.1. Command-line tools are largely unaffected, but internal APIs may shift rapidly.

Changes:

  • 3 Major Enhancements:
    • Renamespaced everything RDoc under the RDoc module.
    • New `ri` implementation.
      • Reads from a cache in ~/.ri/ for enhanced speed.
      • RubyGems aware, only searches latest gem versions.
    • Now up to over 100 tests and 200 assertions.
  • 4 Minor Enhancements:
    • Switched to an ERb-based TemplatePage, see RDoc::TemplatePage.
    • Class/module ri now displays attribute and constant comments.
    • Cross-references can be disabled with a leading \.
    • Relaxed parsing for some RDoc inline markup.

Bugs:

If you found a bug, please report it at the RDoc project's tracker on RubyForge: http://rubyforge.org/tracker/?group_id=627

Synopsis:

  gem 'rdoc'
  require 'rdoc/rdoc'
  # ... see RDoc

Posted in ,  | 4 comments

An RDoc Wiki

Eric Hodel | Fri, 15 Feb 2008 00:14:37 GMT

For fun, I wrote a 200 line wiki a couple of weeks ago using WEBrick and RDoc withRCS as the only external dependency for history. You’ll need a recent build of Ruby 1.9 or Rubinius to run it:

rdoc_wiki.rb

It uses RDoc’s markup for formatting, and stores its content into ~/.rdocwiki as plain text files.

RdocWiki has one special page, /WikiCss that you can use to style things, here’s what I used:

#wiki_edit textarea {
  width: 40em;
  height: 20em;
}
#wiki_edit input {
  display: block;
}
#wiki_restore {
  display: inline;
}

I’d run a copy on Rubinius for you to use, but currently Rubinius is broken on FreeBSD.

Posted in ,  | no comments

RDoc's TemplatePage removed from Ruby

Eric Hodel | Mon, 07 Jan 2008 10:59:54 GMT

If you’ve got a custom RDoc template, it won’t work with the next release of 1.9. I’ve removed the custom TemplatePage and replaced it with an ERB-based version that works similarly.

This should make it much, much easier to write a custom RDoc template as you can now use arbitrary ruby code inside your templates.

It’s really easy to convert an old RDoc template to the upcoming version:

Replace thisWith this
%blah%<%= values["blah"] %>
!INCLUDE!<%= template_include %>
HREF:aref:name<%= href values["aref"], values["name"] %>
IF:blah<% if values["blah"] then %>
IFNOT:blah<% unless values["blah"] then %>
ENDIF:blah<% end %>
START:blah<% values["blah"].each do |blah| %>
END:blah<% end %>

To make nested loops easier to convert, convert START statements to:

<% values["blah"].each do |blah| $stderr.puts blah.keys %>

So you can see what is being used inside which loop.

I’ve also removed the old_html template, as I don’t think anybody uses it anymore, and updated all the existing templates in RDoc to use ERB. (If somebody could double-check my work on the CHM and XML outputters, that would be great.)

Posted in ,  | 11 comments

Unleashing ri

Eric Hodel | Sun, 27 Aug 2006 23:45:00 GMT

Now that ruby 1.8.5 has been released (Changelog) and ri includes a bunch more documentation and integrates with gems you just might be suffering from ri overload. 
$ ri --system -l | wc -l
    8882
$ ri -l | wc -l
   11918
$ echo 11918 - 8882 | bc
3036
I have 31 extra gems installed, including Rails, which gives me a ton more at-my-fingertips documentation! Some people would rather have less documentation, and there are a handful of new options that control where ri will search for documentation. 
$ ri -h
[...]

  --doc-dir, -d <dirname>
                  A directory to search for documentation. If not
                  specified, we search the standard rdoc/ri directories.
                  May be repeated.

       --system   Include documentation from Ruby's standard library:
                    /usr/local/share/ri/1.8/system

         --site   Include documentation from libraries installed in site_lib:
                    /usr/local/share/ri/1.8/site

         --home   Include documentation stored in ~/.rdoc:
                    /Users/drbrain/.rdoc

         --gems   Include documentation from Rubygems:
                    /usr/local/lib/ruby/gems/1.8/doc/*/ri

[...]
Options may also be passed in the 'RI' environment variable
$
I've set my RI environment variable is -T -f ansi to turn off the pager and give me fancy colors, but you can do mix-and-match options to your liking. To only search the system libraries by default, export RI='--system'. To make an alias that searches only rails documentation: 
alias rri="ri -d /usr/local/lib/ruby/gems/1.8/doc/actionmailer*/ri \
              -d /usr/local/lib/ruby/gems/1.8/doc/actionpack*/ri \
              -d /usr/local/lib/ruby/gems/1.8/doc/actionwebservice*/ri \
              -d /usr/local/lib/ruby/gems/1.8/doc/activerecord*/ri \
              -d /usr/local/lib/ruby/gems/1.8/doc/activesupport*/ri \
              -T -f ansi"
(If you have multiple rails versions you'll need to explicitly list the versions of each gem.) 
$ rri ActiveRecord::Base.find
----------------------------------------------- ActiveRecord::Base::find
     ActiveRecord::Base::find(*args)
------------------------------------------------------------------------
     Find operates with three different retrieval approaches:

[...]
Also, note that if you install multiple versions of a gem you'll either need to run gem cleanup and remove the old versions or manually remove their ri if you want the older versions to hang around. If you don't, you might get duplicate documentation.

Posted in ,  | no comments

RDoc Mega Update

Eric Hodel | Sat, 05 Aug 2006 05:08:56 GMT

With many thanks to Hugh Sasse for doing much of the gruntwork, there will be a huge increase in RDoc available in Ruby 1.8.5. If you have the time, get the latest from CVS (HEAD or ruby_1_8) and make install install-doc, check it out, and report back anything busted, poorly worded, or in need of general cleanup.

I have until Sunday night to fix anything you find.

Posted in ,  | no comments

ZenTest RDoc

Eric Hodel | Thu, 27 Apr 2006 02:57:29 GMT

The RDoc for your favorite testing toolset is now online at zentest.rubyforge.org/.

Strangely, my uploading tasks updates the RDoc every time I run it. Maybe I have the wrong task on the right hand side.

desc 'Upload RDoc to RubyForge'
task :upload => :rdoc do
  user = "#{ENV['USER']}@rubyforge.org" 
  project = '/var/www/gforge-projects/zentest'
  local_dir = 'doc'
  pub = Rake::SshDirPublisher.new user, project, local_dir
  pub.upload
end

Posted in , ,  | no comments

Rubygems + ri

Eric Hodel | Thu, 23 Feb 2006 11:42:00 GMT

I’ve almost finished doing what has previously been claimed as impossible. I’ve cleanly integrated ri and Rubygems so that you can use ri to search your installed gems’ documentation.

The first part was simple, tell Rubygems to generate ri data for its gems. Rather than have Rubygems install a gem’s ri data mixed-in with the standard library’s data it installs it into a per-gem directory.

The unfinished part is getting a patch into Ruby that makes ri go looking in the gem ri data directories. That patch is in [ruby-core:7423]. Hopefully I can push it into 1.8 so it will be usable with Rubygems 0.9.

Posted in , ,

I was right!

Eric Hodel | Fri, 17 Feb 2006 10:28:00 GMT

Super-easy!

Except that Rubygems has methods that don’t get called when you think they should.

And that there’s a strange bug in RDoc when you run it twice.

Posted in , , ,

ri for Rubygems will be easy!

Eric Hodel | Fri, 17 Feb 2006 08:44:00 GMT

Something simple as:

begin
  require 'rubygems'
  Dir["#{Gem.path}/gems/*/ri"].each do |path|
    RI::Paths::PATH << path
  end
rescue LoadError
end

Posted in , ,