On Sat, Mar 8, 2008 at 12:20 AM, Trans <[EMAIL PROTECTED]> wrote: > RubyGems should not be generating rdocs. > > As good an example as any for when convention ought to triumph over > configuration, this is it. As it stands we currently must fill out > gemspec options: has_rdoc, rdoc_options and extra_rdoc_files, to get > rdocs generated on install, but that's still not enough to get them > right. For starters, --main README's are missing across the board. > 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. > > 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. 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. > > T.
RubyGems is a package management system. It is common and appropriate that documentation be distributed along with software. RubyGems is unique, however, in that, with a particular documentation system, it generates the documentation on the user's computer, rather than generating it during packaging and including it within the package. It is important to note, that of course any documentation system could be used and distributed within the gem as is common in other packaging systems. However, I consider the fact that documentation is generated on the user's computer to be a significant feature of RubyGems, and agree that it is worthwhile to ensure that an alternative documentation system could be similarly integrated. I agree with your solution, that it should be possible to have a Ruby script, included in the gem, should be executed after installation of the gem. That permits the use of arbitrary programs for documentation, such as rdoc, or other install procedures, such as adding menu items, currently not possible during RubyGems' install process. This, as well, I consider to be a major flaw in RubyGems, which a post-install script would cleanly solve. Of course, this would also require a pre-removal script, and it is important to consider the authority these scripts will be given. Basically, I think it's a fantastic idea. However, I think that same idea directly conflicts with your other proposal. As it stands, it should be fairly simple to allow customization of rdoc generation, having local options override ones contained in the gem, since the rdoc command is neatly separated. If rdoc generation moves into a post-install script, it will become much more difficult to override. Contained within an arbitrary script, there would be no good way to separate the rdoc generation command and override its options. This suggests that a special format or library would be in use for post-install scripts, something like: command_line_task( false, 'rdoc', "--main=README --title 'Cool Program'" ) where false is in an indicator that it's okay if rdoc isn't available, the program will still run. Then the user could set a local option to append '--template=**' any commands to 'rdoc'. Anyhow, I would suggest making a way for the user to change rdoc options locally first, since that should be fairly simple. Adding post-install and pre-removal scripts would be a major change to RubyGems, but I think it's the right choice. Daniel Brumbaugh Keeney _______________________________________________ Rubygems-developers mailing list [email protected] http://rubyforge.org/mailman/listinfo/rubygems-developers
