Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
If the OS allows it, build the docs (ri and rdoc) in a forked background process #352
ri and rdoc are amazingly great, but sadly, many people are impatient, so the Ruby world is filled with advice to add --no-rdoc and --no-ri everywhere, and people are then forced to use their web browsers and visit ruby-doc.org when a quick "ri titleize" would suffice, with much less risk of flow interruption.
This patch attempts to resolve this tension between install-time and dev-time impatience by forking a background process to build the docs after the gems have been installed. The only risk will be if someone tries to use ri or rdoc during the seconds or minutes immediately after the install, which is unlikely and at any rate, there are enough messages that people should realize the docs aren't quite built yet. And all that would happen is that the docs wouldn't be found; no risk of corruption or even misleading errors as far as I can tell.
The code is fairly elegant but it currently relies on the fact that the only user of the done_installing_hooks is the documentation builder. If any other code wants to add hooks then we'd have to make it a little more configurable -- possibly allowing different status messages, possibly adding a new hook array for just backgroundable tasks and restoring done_installing_hooks to just run synchronously like before.
Is there a need to add a "--no-background" option? I can't think of a real use case. If we're on Windows (or another forkless Ruby) it'll revert to synchronous. Perhaps rubygems.org needs to build docs synchronously, but if it's using the RDoc code directly this patch won't affect it.
One thing I feel strongly about is that backgrounding doc gen should be the default behavior. If we hide this behind an option then we're just perpetuating the original problem -- the perception that "gem install" is slow so you should just not install docs. (Which you actually should.)
There are no unit tests yet. It's kind of difficult to unit test
I just tried a clean install of rails and here are some stats:
time to install 2 dozen gems: 13sec
So I guess it's no wonder people prefer --no-rdoc...
I'm not fond with this change beyond posix or windows aspect.
I would rather invest time in making ri lazily generate docs of newer gems
Spawned process could run wildly without control of you install 30 gems in
Sorry for top posting. Sent from mobile.
Nope. Only one process forks; that process generates each gem's docs in turn, just like it happens now (in the original process).
I don't understand. Installing new gems always generates new docs. And the fact that it takes time is entirely the point of this patch.
And this patch is really pretty simple; it took me less than an hour to write and the behavior is isolated to 2 methods (plus a config setting to allow tests to disable it).
Forked process will run, in the background generating documentation for all
A pristine install of rails means around 26 docs of gems that will be
Or is parent process waiting for it to complete? Guess no, if not defeats
Or I'm missing something? Haven't played with your changes so I'm basing my
There was a lazy rdoc generator for "gem server", I would like something
Invoking "ri" coud trigger generation of docs for the newer gems ri is not
Sorry for top posting. Sent from mobile.
Yes and no. Yes, it's in the background; no, you're not unaware of it,
If you want to be able to control it, we could emit its pid -- but
Alternately, if it's too noisy, we could redirect its output to a log
Lazy ri generation doesn't seem great to me since the first time you
Is not actually fear, generating the docs for gems forks a background process, that process will keep adding stuff to the same output (attached), so is not done, stuff is still going on.
But heck, what do I know about that...
Well, that's a shame. The docs for MRI Process.fork clearly say "If
That'll fix it failing. As for not working, well, that's why the