On Mar 19, 12:10 am, Eric Hodel <[EMAIL PROTECTED]> wrote: > On Mar 7, 2008, at 22:20 PM, Trans wrote: > > > [...] Well beyond that it prevents us from all forms of > > customization of our docs, from simply using a different template to > > using a system other then rdoc altogether. The current design > > completely constrains our documentation freedom. > > The current design also gives consistency of documentation across all > installed gems, which has incredible value by itself.
That's true, but I think that's where RI comes in. What would be nice to see is RI become format savy. Currently is spits out ANSI or plain text. If it could spit out other formats like html and xml, and perhaps tex or pdf too, then it would serve very well as this across the board consistent api reference. The main problem with RDocs is that they are static. I see RDocs more as a means for project developers to generate project reference manuals. Right now I think RDoc is trying to straddle two different use-cases --api docs and project manual, and is thus coming up a bit short on both counts. > > A far better solution is simply to designate a conventional location > > for html api docs, say doc/html-api/ or something like that, and just > > have gem server look for them there. > > This is a good idea as an additional feature. Cool. I'm using doc/html/ in my own projects --seems like a reasonable, concise convention. > > For those who would rather generate docs then redistribute them (to > > save package size?) then provide a ruby script that does it, and > > the gemspec can have a field > > to designate that, which it can then run on install. That's much > > simpler solution and much more powerful to boot. > > RubyGems doesn't have a post-install script on purpose. I agree. I don't think the overhead of distributing pre-built docs is much of a price to pay these days if one has special documentation requirements. So post-install scripts for documentation sake is completely unnecessary. Finally I note what would make a big difference for me when documenting a large project like Facets, is support for documentation "groups", maybe via a per file directive ":group: GroupName", or otherwise as command line options. If Rdoc could take that and present those groups separated is some fashion, things would have been much better for me, and I imagine James Britt, at least, might feel the same in his work to document Ruby's standard library. T. _______________________________________________ Rubygems-developers mailing list [email protected] http://rubyforge.org/mailman/listinfo/rubygems-developers
