[Rubygems-developers] Handling documentation

Jim Weirich jweirich at one.net
Fri Nov 28 12:51:57 EST 2003


Richard Kilmer wrote:

> I like the idea of running RDoc over the source.  It would be cool to add
> a:
> 
> 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.

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.

-- 
-- 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)



More information about the Rubygems-developers mailing list