Hi,
First a little background. I am the maintainer of YARD, and we've
recently been getting reports that the RubyGems plugin that has been
shipped with YARD since 2009 is not compatible with RubyGems 1.7.x. I
have a fix in place, but given RubyGems' future, I am unsure how long
the fix will continue to work. I'm posting here in hopes of finding a
way to improve YARD's RubyGems' plugin in a sustainable / maintainable way.
I've just taken a look at the new RubyGems release, and it seems like
has_rdoc is finally going away. While I understand that it's not in the
best interest of the community to allow gem specifications to disable
documentation generation, the 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. 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 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. Ultimately, it should be the
gem author's decision which documentation tool is used to generate their
documentation. As a gem author myself, I do not want any of my
documentation generated with RDoc, because they are not compatible with
the tool, and this affects how effective the locally generated docs are
for my users. This is certainly an issue for other libraries as well,
some of which are fairly popular: like Haml, Sass, DataMapper,
mongo-ruby-driver, Spidr, etc. (a short list can be found here:
https://github.com/lsegal/yard/wiki/Who's-Using-YARD%3F
<https://github.com/lsegal/yard/wiki/Who%27s-Using-YARD%3F>)
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:
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. This most directly
solves the tool problem, because the tool is now no longer part of the
installation process. This suggestion has other really great benefits
too, such as drastically improving install time (as you know, rdoc gen
is the slowest part of a gem install). You've likely seen the complaints
on twitter, and DHH's recent mis-tweet about suggesting --no-rdoc
--no-ri to workaround this issue. Packaging static docs rather than
having the client generate the docs on *every install* will be much more
efficient for everybody.
A few notes about this one: firstly, RG can package basic gem commands
to build the docs quickly with rdoc for the gem author to use; I don't
mind having such basic helper methods in the tool. Secondly, if
doc_files is not present, I wouldn't mind a built-in fallback on RDoc
here either. The specification of the files would allow gem authors to
override the default behaviour, which I think is reasonable. Finally,
the ri parsing can continue to work regardless of the setting. Parsing
the docs for ri is fairly quick, and not really a compatibility or speed
issue.
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 ...). This way, a gem install
could perform an extra fetch of the doc archive file from a separate
repo if present, or skip this extra download if --no-rdoc is provided.
This certainly adds a bit of extra weight to RG's infrastructure, but I
think it would be manageable and quite a helpful addition. Again,
"generate once distribute everywhere" is much more efficient than having
each user re-generate the exact same docs. I think it's clear that many
users are frustrated with having to do the re-generation all the time if
they want the static docs locally.
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. If security is an issue, it could be executed with ruby -S
<doc_bin_file> so as to ensure it's coming from an already installed
gem. At least then, users could specify s.doc_bin = 'yard', or s.doc_bin
= 'rocco'. If this is added, having a `doc_bin_options` would be helpful
too (just like the gemspec currently has rdoc_extra_options). There
might be some compatibility issues with this one, specifically how to
know what the output path is, but nothing insurmountable here.
Again, I really hope we can figure out a way to have all of the
documentation tools co-existing with RubyGems. Given that RubyGems is a
core part of the way Ruby users interact in the ecosystem, I think it's
important for users to have extra choices about things like
documentation et al.
- Loren
_______________________________________________
Rubygems-developers mailing list
http://rubyforge.org/projects/rubygems
Rubygems-developers@rubyforge.org
http://rubyforge.org/mailman/listinfo/rubygems-developers
