Permalink
Browse files

Deprecate RubyGems plugin to allow this to be optional, and fixup docs

  • Loading branch information...
1 parent 87b8da9 commit 8f0b49fdae752adfcb94d642d7aac19a32e8bd27 @raggi committed Jul 19, 2010
Showing with 29 additions and 26 deletions.
  1. +29 −18 README.markdown
  2. +0 −8 lib/rubygems_plugin.rb
View
47 README.markdown
@@ -1,17 +1,17 @@
# Hanna — a better RDoc template
-Hanna is an RDoc generator that scales. It's implemented in Haml, making the sources clean
-and readable. It's built with simplicity, beauty and ease of browsing in mind. (See more
-in [the wiki][wiki].)
+Hanna is an RDoc generator that scales. It's implemented in Haml, making the
+sources clean and readable. It's built with simplicity, beauty and ease of
+browsing in mind. (See more in [the wiki][wiki].)
Hanna gem is available from [rubygems.org][]:
gem install hanna
The template was created by [Mislav][] and since then has seen contributions from:
-1. [Tony Strauss](http://github.com/DesigningPatterns), who participated from the early
- start and made tons of fixes and enhancements to the template;
+1. [Tony Strauss](http://github.com/DesigningPatterns), who participated from
+ the early start and made tons of fixes and enhancements to the template;
2. [Hongli Lai](http://blog.phusion.nl/) with the search filter for methods.
3. [Erik Hollensbe](http://github.com/erikh) a serious refactoring and up to
date with RDoc 2.5.x.
@@ -27,11 +27,15 @@ An alternative is to set the `RDOCOPT` environment variable:
This will make RDoc always use Hanna unless it is explicitly overridden.
-Another neat trick is to put the following line in your .gemrc:
+## Integrating with RubyGems
+
+Another neat trick is to put the following line in your .gemrc, this will make
+RubyGems use Hanna for all rdoc generation:
rdoc: -f hanna
-This will make RubyGems use Hanna when generating documentation for installed gems.
+This will make RubyGems use Hanna when generating documentation for installed
+gems.
### Rake task
@@ -44,7 +48,8 @@ add the hanna format argument to your RDoc::Task options:
rdoc.options.push '-f', 'hanna'
end
-Tip: you can do this in the Rakefile of your Rails project before running `rake doc:rails`.
+Tip: you can do this in the Rakefile of your Rails project before running
+`rake doc:rails`.
Here is an example of a task for the [rdbi library][rdbi]:
@@ -66,27 +71,33 @@ Here is an example of a task for the [rdbi library][rdbi]:
The gem comes with a RubyGems plugin that overrides the gem default arguments
to RDoc to use Hanna.
-To regenerate documentation for a specific gem (say one you installed before
-installing hanna):
+To regenerate documentation for a specific gem, first configure RubyGems to
+use Hanna, by adding the following to your .gemrc:
+
+ rdoc: -f hanna
+
+Now to regenerate documentation for an already installed gem:
- gem rdoc mygem
+ gem rdoc mygem --overwrite
To regenerate documentation for all gems:
- gem rdoc --all
+ gem rdoc --all --overwrite
+To easily browse your newly created documentation, use `gem server`.
## You can help
Don't like something? Think you can design better? (You probably can.)
-I think of Hanna as the first RDoc template that's actually _maintainable_. First thing I
-have done is converted the original HTML template to Haml and Sass, cleaning up and
-removing the (ridiculous amount of) duplication. Also, the template fragments are now in
-_separate files_.
+I think of Hanna as the first RDoc template that's actually _maintainable_.
+First thing I have done is converted the original HTML template to Haml and
+Sass, cleaning up and removing the (ridiculous amount of) duplication. Also,
+the template fragments are now in _separate files_.
-Ultimately, I'd like to lose the frameset. Currently that is far from possible because the
-whole RDoc HTML Generator is built for frames. Still, that is my goal.
+Ultimately, I'd like to lose the frameset. Currently that is far from possible
+because the whole RDoc HTML Generator is built for frames. Still, that is my
+goal.
This is git. Fork it, hack away, tell me about it!
View
8 lib/rubygems_plugin.rb
@@ -1,8 +0,0 @@
-# TODO for rubygems 1.3.8, should get Gem.register_plugin(:documtnation,
-# 'hanna/rubygems').
-# TODO some way of making this optional.
-
-# Could use Gem.pre_install hooks, but that'd not work for `gem rdoc --all`.
-
-require 'rubygems/doc_manager'
-Gem::DocManager.configured_args << '-f' << 'hanna'

0 comments on commit 8f0b49f

Please sign in to comment.