[Rubygems-developers] Handling documentation
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
>> 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
> (3) If the gem is uninstalled, the docs are automatically cleaned up as
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.
More information about the Rubygems-developers