[Rubygems-developers] Handling documentation

Gavin Sinclair gsinclair at soyabean.com.au
Sat Nov 29 10:37:23 EST 2003


On Saturday, November 29, 2003, 4:51:57 AM, Jim 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 believe a central place for documentation is very desirable.  It
makes it easy to browse a single directory and see what documentation
you have available.

> I see a couple of advantages.

> (1) It keeps the docs with the code.

I don't think that's so great.

> (2) Since there is currently no standard place for docs, it establishes 
> a standard (at least for gems).

I'd like to see gems establish a standard as well.  If it proves to be
a good standard, then it can be adopted by Ruby itself, with a
CONFIG::Config['ruby_doc_dir'].

> (3) If the gem is uninstalled, the docs are automatically cleaned up as 
> well.

That is definitely a benefit.  However, it can probably be achieved
even if the generated docs are placed centrally.

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

That's fair enough, but I believe the small guy would benefit from
centralised documentation as well.

Perhaps a happy medium is to generate the documentation inside the
gems dir, and put a symbolic link in the central documentation dir.

The "central documentation dir" can have a default, and an optional
environment variable, and a command-line override.

When I have a firmer grip on the operations of RubyGems, I'll look at
some detailed proposals.

Cheers,
Gavin



More information about the Rubygems-developers mailing list