[Rubygems-developers] Handling documentation

Richard Kilmer rich at infoether.com
Fri Nov 28 10:09:22 EST 2003

On Nov 28, 2003, at 5:25 AM, Gavin Sinclair wrote:

> OK, so since I mentioned it on ruby-talk and Chad and Jim replied
> positively, let's talk about if and how Gems should deal with
> documentation.
> Note: I don't want to waste anyone's time or distract developers from
> the basics, especially with an upcoming release.

Please...its not a distraction...we have been talking about this.

> Anyway, without having thought about it too much, I just figured that
> a gem should contain instructions on how to build documentation (list
> Rake's RDocTask).  So part of installation is running RDoc over the
> source and depositing the output in a predictable place.  Another part
> of documentation installation is perhaps copying some files (ChangeLog
> etc.) verbatim.

I like the idea of running RDoc over the source.  It would be cool to 

gem --rdoc <gem-name> --doc-dir=<path>

And perhaps we could settle on a ENV variable:

RUBY_DOC #= dir to install docs into?

To align with...

RUBY_LIB #=> list of dirs to find ruby files

And what RubyGems already has added...

RUBY_GEMS #=> list of dirs to find gems
> There's plenty of things to talk about wrt default options and
> behaviours, but no need to worry about that now.  I just want to know
> if the way I'm thinking is compatible with you guys.

Very compatible.  Actually, right now the gem spec:

see - http://rubygems.rubyforge.org/wiki/wiki.pl?GemSpecification

You can specify a list of files to be included in the #files array, I
was thinking of also having another array:


Which would have a list of rdoc or whatever doc type you want files
that would be included in the Gem, but would not be extracted during
install...but that you could specify the above mentioned:

gem -i <whatever.gem> --extract-docs --doc-dir=<path>

Or something.

> A related thought is this: RubyGems already has a bit of overlap with
> Rake (like packaging).  Now I'm talking about an RDocTask.  Is there a
> synergy here?  I definitely think so.

Well, Jim can answer this better than I.  But I see Rake as a build
and deploy tool, and gems as the deploy and installation format.

> Cheers,
> Gavin
> _______________________________________________
> Rubygems-developers mailing list
> Rubygems-developers at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rubygems-developers

More information about the Rubygems-developers mailing list