On Apr 5, 2011, at 4:53 PM, Loren Segal wrote: > 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.
If you need a special flag why not have users add a file to the gem? I don't understand why yard has to be opt-in per-gem. Can't yard process any ruby project? That would make more sense to me. >>> 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. If you have a bug in your code that causes yard to fail how can you not need to release a new version? There aren't "a bunch" of 1.8.6 users. Over the last nine weeks 1.8% of downloads from rubygems.org were from ruby 1.8.6. There's a split of about 2/3 1.8.7 and 1/3 1.9.2 with less than 4% on 1.8.6, 1.9.1 or some other version. > 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. IMO hosting static documentation is outside the scope of rubygems. Much of my documentation is hosted either on rubyforge under the project-specific hostname or docs.seattlerb.org. rubygems.org links to rubydoc.info by default but can be set to point wherever the user chooses. I am dubious of this proposal if it's a problem that rubydoc.info hasn't addressed. > 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. Having pre-built documentation in the gem is a no-go due to the size increase. It sounds like this should be a separate project that sits alongside rubygems.org like test.rubygems.org > 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. Sounds like haml isn't being very friendly to its users. Why do we need to do all this work in order to work around a gem author not making it easy to generate documentation? >> 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. Polls are great, but often you'll find more people willing to say "I want X" than will say "I want to implement X" which will be more than say "I want to support X". With the new plugins as described below it is possible to implement this outside of rubygems itself and see how well it actually works. > 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. I know I'm an outlier, but I've worked on nearly 80 gems and am actively working on about 10. An extra command to run (and remember to run) would be a pain. >>> 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? I like the lead rubygems-test has taken on this, add a .gemtest file and rubygems-test will work. > 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. Right, but they're more likely to specify --document=yard, which shouldn't be an issue, correct? If yard needs to care about falling-back properly it can call off to RDoc, right? > 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. I recommend implementing static documentation as a plugin to rubygems. If it becomes a proven solution it can be merged in. _______________________________________________ Rubygems-developers mailing list http://rubyforge.org/projects/rubygems Rubygems-developers@rubyforge.org http://rubyforge.org/mailman/listinfo/rubygems-developers
