On 4/11/2011 7:17 PM, Eric Hodel wrote:
If you need a special flag why not have users add a file to the gem?
That's possible, and something we might have to do. The issue here is
that there is already a perfectly valid field for this type of data. It
just seems to me that making use of the gemspec is a much better place
to store metadata than the filesystem.
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.
Yes and no. Yes, YARD is fairly compatible with standard natural
language documentation and RDoc markup. At the same time, YARD doesn't
support RDoc directives, and doesn't add as much value if the YARD
syntax is not used. Let's ask the reverse question: Can't RDoc process
any ruby project? The answer is similar. Sure, it can generate HTML
files, but those HTML files would look pretty unreadable for a project
like YARD, Haml or Datamapper, since RDoc doesn't support markdown,
textile, or YARD formatting. Certainly many gem authors would not be
happy with docs that did not generate properly on the client's machine.
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?
Perhaps you missed the issue? YARD is not failing, and the bug was not
in our code. RDoc's generation of YARD documentation was failing in a
stock 1.8.6 installation. We had to *work around* a bug in another
codebase (RDoc) just to have docs work in a specific version of RDoc.
With static generation, we would not need to care what RDoc the client
had, since the files would be generated on our end (with our updated
"bug-free" tools).
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.
I'm going by actual reports, not download statistics. We've had numerous
reports about 1.8.6 issues, and still do. Keep in mind that 1.8.6 users
are not all constantly downloading rubygems (in fact the whole issue
here is that users did not update RDoc from the standard install)-- in
fact many new gems dropped support for 1.8.6 (rack, rails) and in many
cases they *can't* download new gems, so going by download counters is
likely heavily skewed.
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
Well that's precisely my point. I'm fine with hosting the docs in a
separate package (and that's indeed what I've been suggesting); but to
do this, it would need more integration. Creating a new gemspec just for
docs would be hugely taxing on maintainers.
Also releasing as a standard gem would make it unable to authors to
update documentation files retroactively if there was a new RDoc tool or
YARD tool that updated bugs / made the templates nicer. See above for a
situation where a gem author might want to update documentation files.
The gem release cycle doesn't fit perfectly with this system.
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?
Again, I think you're missing the point. Haml installs documentation
just fine; the problem is that *to be friendly* to its users, its users
need extra dependencies that they may never use again. Do you think it's
reasonable to require every user of a gem to install "doc-tool",
"doc-tool-plugin", "doc-tool-markup-X" just to get the docs? Perhaps the
question should posed differently: why do *users* need to generate the
documentation if the author can do it once for everybody? I still
haven't really seen an answer to this one. It just seems more logical
and efficient to me that docs be generated once and distributed to all
rather than every user performing the same computation locally to create
(hopefully!) the same end result.
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.
I find this a little hard to believe. The extra command could be easily
automated in a rake task or script. Users using gem packaging tools like
jeweler or hoe could get this functionality virtually without thinking
about it. Don't you use hoe? I can't imagine an extra command would be
hard to add to that tool.
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?
It might be an issue, see the first response on top. By the same token,
they might call --document=rocco, or --document=tomdoc, which would
definitely be an issue if a lib documented with YARD was pulled in as a
dependency. We are not compatible with those tools at all.
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.
Thanks, I will look into using the new post install hooks then.
In this case, is there a way to disable another "post install hook" from
running? For instance, if a static documentation plugin ran, we would
want to disable RDoc/RI from generating. Is this feasible with the APIs,
or do we have to resort to unsupported monkeypatching again?
- Loren
_______________________________________________
Rubygems-developers mailing list
http://rubyforge.org/projects/rubygems
Rubygems-developers@rubyforge.org
http://rubyforge.org/mailman/listinfo/rubygems-developers
