ruby gems doc indexer

[Roger Pack]

Don't know if this would be useful for anyone, but I wrote a utility to
create an html index of the rdoc's of installed rubygems on your system.

I.e.
ruby gem_rdoc_indexer.rb

creates file all_gems_rdocs.html
with contents
---------------

All installed gems: (core)

abstract-1.0.0: homepage (no rdoc)

actionmailer-1.3.3: homepage rdoc README
....
with links to the rdoc's and README's.

example output file:
http://ruby-roger-useful-functions....k/gem_rdocs_indexer/all_gems_rdocs_index.html


how to get:

code:
http://ruby-roger-useful-functions.googlecode.com/svn/trunk/gem_rdocs_indexer/gem_rdoc_indexer.rb



Any feedback welcome.

Question: is there a designated place where rdoc's for the core lib's
are installed, locally?

Also, is it possible to get the specs for say version 1.0 of a gem, and
also the specs for version 2.0? Currently this isn't handled perfectly.

Thanks!

-R

 

[Joel VanderWerf]

Don't know if this would be useful for anyone, but I wrote a utility to
create an html index of the rdoc's of installed rubygems on your system.

Nice to have direct links to the home page, as well as local docs.
That's a missing feature in my own indexer, but I like the table in
mine. (Yes, I know about gem server.) Feel free to adapt from the
following (which I run every so often after updating gems). The title
field is not very useful, because most rdoc users don't know about that
option.

require "amrita/template"
include Amrita

Dir.chdir "/usr/local/lib/ruby/gems/1.8/doc"

tmpl = TemplateText.new <<END
<title>Gem Docs</title>
<table border="1">
<tr><th>Name</th><th>Title</th><th>Gem Docs</tr>
<tr id=table1>
<td id="name"></td>
<td id="title"></td>
<td><a id="gemdocs"></a></td>
</tr>
</table>
END

links = Dir['*/rdoc/index.html']

linkdata = links.sort_by{|s|s.downcase}.map do |link|
{
:name => link[/(.*?)\//,1],
:title =>
File.open(link).grep(/<title>/)[0][/<title>(.*?)<\/title>/,1],
:gemdocs => ahref=>link) { link }
}
end

data = {
:table1 => linkdata
}

tmpl.prettyprint = true
tmpl.expand(File.open("index.html", "w"), data)

puts "rebuilding fast-ri index..."
system "fastri-server -Bb"
puts "done"

 

[Eric Hodel]

Don't know if this would be useful for anyone, but I wrote a utility
to
create an html index of the rdoc's of installed rubygems on your
system.

How is this different from running `gem server` and navigating to that
URL in your browser?

 

[Roger Pack]

How is this different from running `gem server` and navigating to that
URL in your browser?

In all honesty, I didn't know gem server existed, and, also honestly, it
didn't make sense for me that gem server would be necessary for browsing
an index of rdoc's.

My 'wish' would be something like this run automatically after
installing new rdoc's:

gem install package
...
package installed
updated index gem_rdoc_index.html

It just makes more sense than having to run a server to browse rdoc's.
Thoughts?
I'd be happy to code it up as a patch

-R

 

[Joel VanderWerf]

How is this different from running `gem server` and navigating to that
URL in your browser?

20Mb of RSS to serve one static page.

Yeah, ok, some people sneeze in 20Mb chunks.

I do like the look of the gem server page (has it changed recently?).
Why can't this be generated to some file after every gem update?

 

[Roger Pack]

How is this different from running `gem server` and navigating to that

In all honesty, I didn't know gem server existed, and, also honestly, it
didn't make sense for me that gem server would be necessary for browsing
an index of rdoc's.

Also it has a link to the README, which is nice. Typically maintainers
show their README in the rdoc's index with their own rdoc's, but don't
set it up that way for the gem, for some reason.

-R

 

[Eric Hodel]

In all honesty, I didn't know gem server existed, and, also
honestly, it
didn't make sense for me that gem server would be necessary for
browsing
an index of rdoc's.

My 'wish' would be something like this run automatically after
installing new rdoc's:

gem install package
...
package installed
updated index gem_rdoc_index.html

It just makes more sense than having to run a server to browse rdoc's.

Thoughts?
I'd be happy to code it up as a patch

`gem server` is already a well-known way to access documentation. It
provides a --daemon option so you can start it and forget about it.
(It updates itself as new gems are installed.)

This is an entirely new way of accessing the same information that
isn't going to be well-known. Furthermore, the path to this file is
either going to be in an obscure location to support multiple users,
or only accessible by one user.

I don't want to maintain two different ways of accessing the same
information.

 

[Vince Angeloni]

This is an entirely new way of accessing the same information that
isn't going to be well-known. Furthermore, the path to this file is
either going to be in an obscure location to support multiple users,
or only accessible by one user.

I don't want to maintain two different ways of accessing the same
information.

For the single user at home, this is an ideal solution. I have no desire
to use gem server just to view RDOCs. Robert, your code works like
a charm and I think it is extremely useful. Thanks so much for sharing.

vince

 

[Jeremy McAnally]

You do realize that gem server that serves up the docs is just a
simple WEBrick server right? I use it all the time. It's super
simple to crank up and kill off.

But to each his own.

--Jeremy

For the single user at home, this is an ideal solution. I have no desire
to use gem server just to view RDOCs. Robert, your code works like
a charm and I think it is extremely useful. Thanks so much for sharing.

vince

--
http://jeremymcanally.com/
http://entp.com

Read my books:
Ruby in Practice (http://manning.com/mcanally/)
My free Ruby e-book (http://humblelittlerubybook.com/)

Or, my blogs:
http://mrneighborly.com
http://rubyinpractice.com

 

[Roger Pack]

`gem server` is already a well-known way to access documentation. It

provides a --daemon option so you can start it and forget about it.
(It updates itself as new gems are installed.)

Yeah that works too. Either way is fine. My personal preference is the
more light weight one. If it were up to me I'd deprecate the server and
go more in that direction.
But that's just me.

Some clarifying thoughts:
Twould be nice to have a link there to the code itself, as well as the
rdoc's [for perusal], and the README's. And to the normal rdoc's for
ruby should they happen to be installed.
Thanks!
-R

 

[Roger Pack]

Some clarifying thoughts:

Twould be nice to have a link there to the code itself, as well as the
rdoc's [for perusal], and the README's. And to the normal rdoc's for
ruby should they happen to be installed.

Twould be nice to have some access to any existing 'changelog', too,
from gem server, and also to the unpacked gem files themselves [which
would satisfy that]. Not sure if that's possible.
-=R