rdoc, rdoc_chm, rdoc_html_templates 2.3.0 Released

Eric Hodel | Thu, 29 Jan 2009 01:07:00 GMT

RDoc version 2.3.0 has been released!

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.

Release notes

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 RDoc 1.0.1. Command-line tools are largely unaffected, but internal APIs may shift rapidly.

See the RDoc documentation for a description of RDoc’s markup and basic use.

Changes:

  • 3 Major Enhancements
    • Michael Granger’s Darkfish generator is now the default for HTML output
    • Various rdoc generation speedups by Hongli Lai. Patches #22555, #22556, #22557, #22562, #22565.
    • rdoc/discover.rb files are loaded automatically from installed gems
  • 8 Minor Enhancements
    • Added a space after the commas in ri class method lists. RubyForge enhancement #22182.
    • Improved ri—interactive
    • Generators can now override generated file locations
    • Moved unmaintained CHM generator to it’s own package
    • Moved unmaintained extra HTML templates to their own package
    • Removed experimental texinfo generator
    • Converted to minitest
    • Known classes and modules list outputs once per line now for grep
  • 11 Bug Fixes
    • Fix missing superclass in ri output
    • Fix an RDoc crash when told to parse an empty file
    • Ignore nonexistent files instead of crashing
    • .txt and .rdoc files are always considered text. Patch #22897 by Aaron Patterson.
    • When merging ri data with a nonexistant directory, RDoc no longer crashes
    • Fix visibility of methods in XML output. Issue by Yehuda Katz.
    • Fixed relative link generation
    • Fix crash, RDoc now ignores comments above local variable assignments in modules
    • RDoc now only accepts adjacent comments for rb_define_module and rb_define_class
    • C file RDoc is no longer included in token stream
    • Scan all gem paths to match gem name for ri output

Posted in ,  | 2 comments

RubyGems code_swarm

Eric Hodel | Wed, 28 Jan 2009 00:59:32 GMT

I built a code_swarm visualization of the RubyGems repository history:


RubyGems code_swarm (HD) from Eric Hodel on Vimeo.

Coincidentally, you can find a code_swarm visualization for Rails and other projects by Ilya Grigorik. He points to Peter Burns’ fork on GitHub which has a much improved toolset for generating these types of visualizations.

I used the original repository which involves a lot more work. For RubyGems I did roughly the following:

  1. Get a log: svn log -v > rubygems.log
  2. Convert the log: python convert_logs.py -s rubygems.log -o rubygems.xml
  3. Munge the XML to remove the CVS conversion commits and hide the renames from trunk/rubygems/ to trunk/
  4. Run code_swarm: code_swarm rubygems.config
  5. Encode PNGs to an MP4: ffmpeg -f image2 -b 1500 -r 24 -i frames/rubygems-%05d.png -sameq rubygems.mp4
  6. Upload to Vimeo

I played around with the code_swarm configuration a bit and ended up with this config for code_swarm. My changes give a larger video with more lingering of files as they float around and bumps up font sizes for readability. For more active projects you may need to decrease FileLife and PersonLife. (Really, I’m not sure how they affect things.)

Posted in ,  | 3 comments

/usr/bin/gems reports "Gem::manage_gems is deprecated"

Eric Hodel | Fri, 16 Jan 2009 00:49:00 GMT

I was looking through my search keywords and found that a lot of people were searching for: 

/usr/bin/gem:10:Warning: Gem::manage_gems is deprecated and will be removed on or after March 2009.

To fix this you need to remove /usr/bin/gem and symlink it to the proper gem executable.

Since RubyGems 1.0 the gem executable has been installed with a name matching your ruby executable. Often when you install Ruby through a packaging system the ruby executable is installed with a version appended like "ruby18" and a symlink named "ruby" points to the real ruby. For the "gem" executable you need to do this yourself.

To prevent problems like this in the future, read RubyGems release notes when you upgrade. RubyGems now prints them out after gem update --system and you can always find the RubyGems release notes posted as news items on RubyForge.

First, determine where the real gem executable is. You can figure out what the ruby executable's real name is like this: 

$ gem env | grep 'RUBY EXEC'
  - RUBY EXECUTABLE: /usr/bin/ruby18

So your gem executable should really live at 'gem18'. Try it: 

$ gem18 env | grep 'RUBY EXEC'
  - RUBY EXECUTABLE: /usr/bin/ruby18

To be extra sure, compare the full gem18 env output and gem env output.

To fix the warning, remove the gem executable and replace it with a symlink to gem18. 

sudo rm /usr/bin/gem
sudo ln -s /usr/bin/gem18 /usr/bin/gem

Now the warning should be gone.

Remember, to prevent problems like this in the future, read RubyGems' output when you upgrade. RubyGems also prints the release notes when you run gem update --system now.

PS: If you're seeing rake give this warning, that's an entirely different issue. Jim Weirich has a fixed rake in his release queue and it should be out before Gem::manage_gems goes away.

Posted in  | 2 comments