Hey Eric,
On 4/5/2011 6:17 PM, Eric Hodel wrote:
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?
We're basically monkeypatching the install_ri/install_rdoc functionality
right now. If has_rdoc isn't set, YARD just silently lets RDoc do its
thing without issue. The failure we had was because the
Gem::Specification class was refactored to remove the overwrite_accessor
feature, which we relied on. The new plugin code will throw out a
standard attribute if that method is not present-- and, again, if that
attribute stops getting checked, it should just fail gracefully.
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.
Well, by the same token, many versions of RDoc and YARD have bugs that
cause problems for gems. For instance, we just (finally!) pulled in a
change that fixes a really old bug in the RDoc shipped with 1.8.6 that
causes parsing of YARD's code to fail: http://bit.ly/hyD9qu -- users
with 1.8.6 (and there are a bunch) still report this error every now and
then. Having static docs, we wouldn't have to deal with modifying
anything in YARD's codebase and putting out another release just to fix
the docs, we'd just need to push static docs.
Keep in mind this would also allow maintainers to package docs that are
generated neither by rdoc or any other ruby doc tool-- ie. statically
hand crafted docs. Although that might sound crazy, there are a handful
of authors that might be interested in this capability. In fact, having
run rubydoc.info for the last little while, we've actually gotten a few
people asking if they could host static files on the site (unfortunately
we can't) for this exact purpose. Some gem authors actually want to have
extreme control over what their html docs look like, and perform
post-processing on the html generated by tools like rdoc and yard, then
host the docs on their own sites for this reason.
Here are two more attempts at convincing you, and then I'll move on:
The speed issue: again, generating the docs is slow. YARD is even slower
than RDoc (although not by that much), so the tool is not the solution.
Munging a bunch of HTML files is just a slow process. Users often want
documentation locally, but don't necessarily want to wait 30-60 seconds
to get it. I've actually gotten requests from users on where they can
download the static rails docs that we host on rubydoc.info, so we made
the package available. Why generate it yourself when you can download
400kb or even just a few MB of data? That's 60 seconds vs. 0.5-2
seconds; epic win. No tool can beat that. I'm pretty sure users would be
drooling over something like this, and improve the amount of users
actually bothering to install docs. Even *I* use --no-rdoc --no-ri
because of speed issues. OTOH I wouldn't turn it off if it was just a
static download away. Yes, yes, it's certainly anecdotal, but I'd wager
that other users feel the same way. If so, more users getting the docs
== a good thing.
Secondly, there are plugins and dependencies to deal with. YARD supports
a variety of plugins, and increasingly, gem authors are making use of
these. A gem author might use plugin X, but it isn't present on every
user's system. Instead of adding a [potentially large] dependency on a
gem *just to generate the docs*, it would be way better to just let the
author have the dependencies on their system and not have the users
worry about this. Consider this: Haml generates its YARD docs with `-m
markdown --markup-provider maruku`, meaning it uses Markdown formatting
through the Maruku library. This means to generate YARD docs on a `gem
install haml`, it needs to first install maruku, which in turn depends
on `syntax`. That's 2 extra gems just to generate the docs on the client
side. All of this could be avoided by allowing the Haml guys to release
a statically generated doc package. I'll bet RDoc might have similar
issues with third party plugins.
It's also an extra step that authors (that don't use Hoe) would have to
implement.
I'm not sure this extra step would be a big deal to most gem authors. It
would be interesting to take a poll on this and see; I'd bet you'd get
enormous support in favour of pre-built docs. Again, if the docs package
isn't present, RubyGems can do the standard local generation it always
has, with whatever tool is present, etc.. It would only be if this
package was found that it would be fetched. This gives gem maintainers
the *choice* to release static docs if they care and want their users to
have fast installs.
I've never used hoe, nor do I use any variant of release-tool to package
my gems, and I've had no issue. `gem build` and `gem push` is sufficient
for me. If there was a `gem build_docs <directory>` and `gem push
<docpkg>`, that would be super easy to use. I don't see this as being a
big barrier to entry; certainly not that complicated that you'd need to
bring in a tool like hoe. I wonder if Nick knows anything about how
complicated this would be to add from the Gemcutter side of things.
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:
*snip*
There will also be a hook to change the default documentation set from %w[ri
rdoc], probably on Gem.configuration
I like this idea. You've just reminded me that I've wished the RubyGems
plugin API had this functionality many many times.
However, there are a few downsides with doing things this way:
1. It's still kind of important to allow gem authors to pick which tool
their docs can be generated with. Again, some authors care a lot about
what their docs look like, and this is problematic when a tool is not
compatible with their documentation format. YARD formatting, for
instance, doesn't look very good at all when generated by RDoc (or
rocco, or tomdoc), and as a gem author I'd want the ability to opt out
of the client using other tools, if yard was available. I'm guessing the
authors who use YARD formatting in their docs would agree with this as
well. I certainly understand that allowing the client to choose is
important (give them overrides), but the authors should have a say, too.
Don't you agree?
2. If a user was gem installing gemX that depended on yard, or some lib
that used YARD formatting, their command `gem install --document=rdoc`
would apply to both libs (right?). In other words, if gemX used RDoc
formatting and the dependency did not, they'd be stuck generating the
wrong type of docs for at least one of the libs. So again, there *is*
some validity to making this a per-gem setting.
Again, I'd really opt for the extra docs package, I think it's the way
to go and solves more of the problems than post install hooks. That
said, I think your solution should be implemented as well, and should be
the fallback. ie. RubyGems should look for a static docs packaged-- but
if not present, we can use the great post install hook idea with
--document, etc.
- Loren
_______________________________________________
Rubygems-developers mailing list
http://rubyforge.org/projects/rubygems
Rubygems-developers@rubyforge.org
http://rubyforge.org/mailman/listinfo/rubygems-developers
