[Rubygems-developers] Handling documentation

Richard Kilmer 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 
>> 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.
>

Chad and I were just chatting about this.  Here is what we have right 
now:

<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 
arrived at:

<Gem.dir>/doc/<gem-full_name>/... # gem docs extracted
<Gem.dir>/doc/<gem-full_name>/rdoc/... # rdoc generated upon gem 
installation

And we can add to the webrick stuff the ability to browse your 
documentation!


> 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
> http://rubyforge.org/mailman/listinfo/rubygems-developers
>



More information about the Rubygems-developers mailing list