[Rubygems-developers] Handling documentation
rich at infoether.com
Fri Nov 28 13:11:10 EST 2003
On Nov 28, 2003, at 12:51 PM, Jim Weirich wrote:
> Richard Kilmer wrote:
>> I like the idea of running RDoc over the source. It would be cool to
>> gem --rdoc <gem-name> --doc-dir=<path>
> Regarding "--doc-dir=<path>": Is there any reason to not install the
> generated documentation into the directory where the gem is unpacked?
> I typically use and "html" directory for this (unformatted document
> source is put into "doc").
> I see a couple of advantages.
> (1) It keeps the docs with the code.
> (2) Since there is currently no standard place for docs, it
> establishes a standard (at least for gems).
> (3) If the gem is uninstalled, the docs are automatically cleaned up
> as well.
Chad and I were just chatting about this. Here is what we have right
<Gem.dir>/spec #=> gem spec files one for each installed gem
<Gem.dir>/cache #=> copy of installed gem files
<Gem.dir>/<gem-full_name>/... # gem source
He convinced me docs should be in the gems dir, so here is what we
<Gem.dir>/doc/<gem-full_name>/... # gem docs extracted
<Gem.dir>/doc/<gem-full_name>/rdoc/... # rdoc generated upon gem
And we can add to the webrick stuff the ability to browse your
> One downside is that large networked sites that like to keep platform
> independent data (e.g. docs) on a share drive separate from the
> platform specific stuff will have to do something special. But if we
> provide an override, then large sites can do what they want with the
> default making sense for the small guy.
Well, if docs are in the gem dir, cross platform gems will be with
their docs (on networked drives) and platform specific docs will be
with their gems.
> -- Jim Weirich jweirich at one.net http://onestepback.org
> "Beware of bugs in the above code; I have only proved it correct,
> not tried it." -- Donald Knuth (in a memo to Peter van Emde Boas)
> Rubygems-developers mailing list
> Rubygems-developers at rubyforge.org
More information about the Rubygems-developers