On Apr 4, 2011, at 12:17 PM, Loren Segal wrote: > … the [has_rdoc] field has performed another task of differentiating gems > with RDoc/YARD documentation for at least the last 2 years; at least with the > addition of the YARD plugin.
How does YARD fail when there's no special flag? > Removing the field (as 1.7.x has) disables the plugin from letting gems > specify which documentation tool their gem is compatible with. If my history > serves me right, the has_rdoc field was introduced for this very reason > (although at the time documentation tools in question were different). The > YARD plugin packaged has made use of this "unused" field to do just that. I think this was more to allow gem authors to say "I'm lazy and can't be bothered to write documentation". > I think it's important to accept that there are many other documentation > tools in Ruby's ecosystem than RDoc; and it's not even just YARD. Rocco is > another great new documentation tool that deserves integration into the > ecosystem as well. Although I'm aware the RubyGems maintainers also work on > RDoc, I don't see any reason for RubyGems to be hardcoded with support for > only one documentation tool. Agreed, Gem::DocManager is not very useful to RDoc, either. > Clearly it would be worthless to just come in here and complain that things > are broken. Again, although I've fixed the problem in YARD, it requires even > more hacking in RubyGems internals, something I hate doing just as much as > you likely hate me doing it. Therefore, I want to figure out a way for all of > us to move forward productively. In that vein, here are a couple of suggested > alternatives to has_rdoc that also solve some other issues raised by the > community: Yes, one thing you can guarantee about monkey patches is that they'll probably break. > 1. Add a `doc_files` field instead. Just like `files` and `test_files`, it > may be useful for gem maintainers to package their own *statically generated* > documentation files to the gem package. While this won't be true for every package, for rubygems-update the generated rdoc HTML by itself (481K as a tar.gz) is twice the size of the current gem (252K). This would triple costs for downloading and storing gems without ri data. > 2. If extra bloat to gem package size is an issue with #1, perhaps we can > give gem authors the ability to package these documentation files separately > from the gem itself and push the documentation package independently of the > gem (gem push_docs …). I'm not fond of this as newer versions of rdoc (or yard) may fix bugs or add useful features that will Just Work on existing sources. It's also an extra step that authors (that don't use Hoe) would have to implement. > 3. Add a `doc_bin` if none of the above are feasible. This would allow gem > authors to specify the [Ruby] command to execute when installing a gem. I have an alternate solution: Add aadditional hook to the rubygems install sequence, pre_installs and post_installs (plural). For example: $ gem install rails -i ~/tmp/gems [pre-installs with 24 gems] [pre-install for activesupport] Successfully installed activesupport-3.0.5 [post-install for activesupport] [pre-install for builder] Successfully installed builder-2.1.2 [post-install for builder] […] [pre-install for rails] Successfully installed rails-3.0.5 [post-install for rails] 24 gems installed [post-installs with 24 gems] Additionally --no-rdoc and --no-ri will be replaced with a --[no-]document option which will take a list of documentation types to generate: gem install rails --no-document # generate no documentation gem install rails --document # generate rdoc and ri documentation gem install rails --document=ri,rdoc # same gem install rails --document=ri # generate only ri documentation gem install rails --document=yard # generate yard documentation There will also be a hook to change the default documentation set from %w[ri rdoc], probably on Gem.configuration _______________________________________________ Rubygems-developers mailing list http://rubyforge.org/projects/rubygems Rubygems-developers@rubyforge.org http://rubyforge.org/mailman/listinfo/rubygems-developers
