Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Turn off ri and rdoc generation by default #42

Closed
wants to merge 1 commit into from
@dhh

Hi guys,

It seems like everyone and their mother has --no-ri and --no-rdoc in their .gemrc file. Any objections to pulling that convention upstream?

@bjreath

+1

@ismasan

+1

@jeremyherbert

+1 please dear world please

@blahed

+1

@Yardboy

+1

@jm
jm commented

+1 definitely.

@mariovisic

+1 ri and rdoc are available online usually so it's only useful for offline coding (in which case you could generate your own documentation very easily).

@kouky

+1

@darrenterhune

+ten hundred million thousand... I win

@luke0x

Would --no-ri be needed in install_update_defaults_str too?

@campreb

+1

@radar

Holy crap @ response.

+1

@radar

P.S. / FYI: my mother doesn't have this option turned on

@jackhq

+1

@lewisou

+1

@cclow

+1

@joeyw

+1

@naudo

+1

@joho

+1

@thorncp

yes please

@ihower

+1

@databyte

+1.01

@leondu

+1

@foxzool

+1

@xiaods

+1

@athak

+1

@DBA

+1

@DylanFM

+1

@benatkin

YES!

@davemcp

+1

@don

+1

@zenmatt

+1

@shairontoledo

+1 and less .files to config

@kovyrin

+1

@alassek

+1

@plentz

+1

@samgranieri

+1 FTW!

@sikachu

+1 on this. If someone wants ri/rdoc they can put --with-ri --with-rdoc in their .gemrc file ;)

@drbrain
Owner

~/.gemrc allows you to turn off RDoc generation.

See gem help env for details.

@levifig

Yes, please!!!

@fmeyer

+1

@ryanrray

+1 think of all the bandwidth and man hours saved.

@marcusp

+1

@srbaker

Eric, thank you for giving me one page I can parse for the GitHub user names of people who I have completely lost respect for.

@capotej

+1

@tikhon

+1

@amerine

@drbrain the point is that it seems most people are already configuring their .gemrc to ignore them by default. This just solidifies the movement in that direction by making it the default.

@eploko

+1

@heffay

+1 !!!!

@tehviking

+1, also configured in my .gemrc, would love to see it gone.

@JackDanger

+1 (partially because I want this, mostly because I want to make this fucking massive thread longer)

@fbjork

+1

@ghg

+1

@jdecker

+1

@NARKOZ

+1

@drbrain
Owner

I don't see any argument here for turning off document generation.

It's easy to turn it off document generation by default.

It's useful to newbies to have documentation enabled by default as there is no need to search for documentation, it's present from both ri ClassName or gem server.

@joho

@drbrain i actually think newbies are much more likely to go to google - how do you even know to run gem server?

@TaopaiC

+1

@bjhess

+1

@febuiles

@drbrain: I might be wrong on this, but I assume most newbies are not aware of the existence of ri or gem server. If most of the people is turning this off on every installation (and I might be wrong on assuming that too), wouldn't it be a saner default to turn it off and let the people who use ri activate it if they want access to it?

@levifig

@febuiles hit the right argument!

@mogest

+1. If, for some reason, the maintainers are against this fantastic idea, then kindly abbreviate -D to mean --no-ri --no-rdoc.

@kotedo

+1

@kingink

+1

@neh

+1

@densone

+1

@pjb3

+1

@tgildea

+1

@ghost

+1

@ejw

+1

@dsafar

+1

@pjdavis

+1

@nestegg

+1

@drbrain
Owner

If documentation is never generated by default where is the incentive for gem authors to write any documentation?

RubyGems has become more aggressive about generating documentation. RubyGems no longer respects Gem::Specification#has_rdoc.

I don't see how turning off documentation generation by default is good for the community.

mogest, 1.7 will replace --no-rdoc and --no-ri with a single --[no-]document option (which should be automatically aliased to --[no-]doc by optparse) making this easier to do.

Of course, --no-rdoc and --no-ri will remain for backwards-compatibility.

@jvnill

+1

@envoked

+1

@postmodern

-9000

Turning off RDoc generation is justifiable. But I and other developers frequently use the ri / yri utilities to quickly check docs. Local documentation indexes are also handy when you don't have internet access to check rubydoc.info.

@nestegg

@drbrain: My issue is that I develop on one machine on which I might want the documentation (although I rarely use local docs). But, I have dozens of staging + production machines that I definitely don't want docs generated on. This means having to make sure to create a .gemrc on all of those machines before any installs are done. I think if you want docs you should enable them, not the reverse.

@parndt

I'd say, without any proof, that most users don't even bother to read the built in documentation and would use, say, rdoc.info or google or the project's readme instead. Day to day performance working with gems would be improved if documentation generation was opt-in rather than opt-out. I'd also tend to think that non-development systems (aka production, staging) would benefit from this performance increase and space saving.

These docs take a huge amount of space on the system (especially when working with multiple gemsets) and are available to be generated whenever you want them anyway. Also, I've seen so instances where the rdoc generation just freezes up on systems where rdoc is outdated and therefore issues get filed on the project itself when it is not the project at fault.

I'm fully behind documentation itself and believe there's a huge incentive for gem authors to write documentation even if this were to be opt-in. Decent documentation reduces the amount of emails received asking "how do i..." and also provide a solid base for having lots of users and a great community that understand the software so why wouldn't you write it? ;-)

Of course, regardless of any of this, this change should not be made before rubygems 2.0 as it is a breaking change to existing .gemrc files or existing expectations.
Plus, those of us who do want local docs can just enable it in our .gemrc files.

Obviously a dividing issue though.

+1 opt-in doc generation

@postmodern

Also, I've seen developers who disable RDoc/RI generation, which allowed syntax errors to slip into their documentation. When end-users install these gems, they see a slew of embarrassing and trivial-to-fix typos in the documentation. Normally I manually generate the documentation and check for warnings, but having RDoc/RI generation enabled by default is extra layer of safety.

@andoy

+1

@vinbarnes

+1 we don't need no stinking docs!!!

@karuna

how about some parameters on setup.rb ?
I usually use --no-ri only.
but on server definitely --no-ri --no-rdoc.

@BinaryMuse

Can we +2?

@matthewrudy

+1 for sure!

@andyss

+1

@corck

+1

@bmoelk

+1 Please do anything and everything to speed rubygems up.

@nragaz

+1

@bbhoss

Please

@colszowka

Could people please refrain from posting plain "+1"s here? I think it's kind of clear by now that this is a topic that should be discussed, and all those +1s make it harder to follow the actual discussion going on here.

@benatkin

I agree with @bmoelk, please speed rubygems up! It takes precedence over encouraging people to write a specific type of documentation.

BTW interesting pull request #. Takes me back to a commit from 2008. :)

@srbaker

The thing is, not all votes are created equal. +1 all you want, but this issue has been closed. That's a -∞.

@JackDanger

@drbrain, @postmodern: This issue is about defaults and it seems pretty obvious from this horde of comments that most users want no documentation generated when they install gems. Nobody on this page is arguing that documentation be removed, only that the default be swapped.

When I b0rk a deploy and have to install a gem to get my server back up I'm enraged to watch 85% of my gem install time taken up by documentation. It's absolutely infuriating.

I haven't ever, in the better part of a decade with Ruby, needed locally-generated docs. I read the source or I google it.

@bronson

+1 This really affects new users: "It takes 20 seconds at 100% CPU to install a freakin gem? That's insane. Ruby must really suck."

@m4n

+1

@osaris

+1

@sunkencity

I give -1 for the patch, but would like to suggest that the documentation should be built by the author of the gem at buildtime, it seems like an incredible waste of electricity to do this on every client machine. I like that there's going to be a shorter alternative to "--no-ri --no-rdoc".

@rwoeber

+1

@postmodern

@JackDanger Perhaps this is more an issue with the performance of RDoc. If RDoc or YARD was blazingly fast, would this still be an issue? Also, what about only generating RI indexes upon install, and disable generating actual documentation.

@raggi
Collaborator

The speed of RDoc generation is a solvable problem. If that is your problem, then solve /that/.

Don't you all use bundler now anyway? :-P

@ujk

+1

@mmack

+1

@daeltar

+1

@JackDanger

@postmodern

"If RDoc or YARD was blazingly fast, would this still be an issue?"

Functionally, less of an issue. But I think generating docs on install is in the same class as running the gem's tests on an assortment of Ruby versions on install. Good for holding gem authors accountable? Sure. A waste of time for 98% of end users? Yes.

"Also, what about only generating RI indexes upon install, and disable generating actual documentation."

That would be better, but I still wouldn't ever use it. We've got rdoc.info and I've got a terminal alias for opening any gem's source in my editor. If I actually need more, I suppose I could spend the few seconds to run ri and rdoc.

@postmodern

@raggi Well played/trolled. It's true, most people are using Bundler to deploy apps, and Bundler disables RDoc/RI when installing gems.

@seymour

+1

@eltiare

+1 x 10000000000000000000000000000000000000!

@zdavatz

+1 extra

@bbhoss

This has to be some kind of load test on Github. Also, my email inbox. Why oh why did I ever comment on this‽‽‽‽‽‽

@matthewrudy

@bbhoss there needs to be a way to unsubscribe.

@postmodern

#43

A compromise. Disable the generation of RDoc HTML generation, while leaving RI index generation enabled.

@paulca

+42

@sloser

+1

@seb

+1
Funnily 1 month ago, i was saying the same on twitter :
"Seriously guys, cloud computing works for docs. gems ri & rdoc generation should be turned off by default #annoying #timeconsuming #ruby"

@Narnach

+1

It's usually the first thing I add to ~/.gemrc on a new machine.

@yzhang

+1

@andion

+1

@kavu

+1
Count me in, too.

@aganov

+1

@ghost

+1

@maik

+1

@binarycode

ПОСОНЫ, НЕ ПИШИТЕ СЮДА, ПОТОМ БУДЕТ НА ПОЧТУ СПАМ СЫПАТЬСЯ

@delwyn

+1

@apetrov

+1

@galex

+1

@saberma

+1

@tilsammans

Definitely. The three people on Earth who use ri and rdoc can enable it themselves.

@weibel

+1

@wjessop

+1, when I was learning Ruby I never referenced the local documentation always favouring the better formatted and more easily read/cross-referenced/searched online docs.

@sgonyea

That's a terrible argument. If documentation is not generated by default, apathy will set in? When I want docs, I will either use YARD or (more commonly) peruse the gem's source. I'd wager that RDoc's invasive auto-generation is nowhere to be found on someone's "reasons I document my code" list.

The defaults are annoying. Lots of people disable it, once the "christ this is dumb" finally boils over. Even more of an argument for shutting off this behavior. "Newbies" are not going to make use of rdoc or ri, at the command line. I've never met one who did.

@bnhymn

+1

@sgonyea

@postmodern's compromise isn't bad either: #43

And RDoc generation can be done lazily. (Not part of his patch)

I hate it. I do not turn it off in .gemrc, because I do not sweep irritations under the rug. (Rather: I patiently wait for them to boil over and into a rage-patch).

@aledalgrande

+1
Please disable Yard by default too if it's installed.

@hashmal

+1

@colszowka

Dammit, how do I unsubscribe from this??

@speedmax

+1 oh yeah

@libo

+1

@kent

+1

@erossetto

+1

$ cat .gemrc
gem: --no-ri --no-rdoc

@jlecour

I don't want to add a simple +1, but I agree 100% ; the common usecase seems to be a mere "install and forget".

@PabloC

+1

@ghost

+1

@shaliko

+1

@nruth

+1

@andyl

+1

@dennyabraham

when i was a young rubyist, despite knowing about the commandline availability of rdoc, because of the inconsistent quality and helpfulness of the available documentation for some gems, i asked internet for help. if internet was out of reach, i read the code itself. in retrospect, this was more helpful than the documentation itself (and why i always install qwandry or gemedit now)

years later, what happens more often now is that i've built a new machine with a brand new provisioning script and i realize building it takes far longer than it should. this is largely my fault for not remembering the additional step of prepopulating every gem installing user's .gemrc, but if we're going to get serious about ruby deployment, should we really have defaults that aren't amenable to production environments?

so ultimately, i agree that document generation should be opt-in rather than opt-out. other remedies (including some i see above) include:

  • pregenerated documentation

  • document generation as a secondary step

  • a rubygems installation flag to disable document generation

@leandro

+1! I always wanted that.

@rbialek

+1

@libo

David since you are in the mood of fixing stupid thing, would you patch github to add a button to STOP the email notification of these tread.
My iPhone keeps on vibrating like a Motorola StartTac.

...or is just me that is missing the damn button! :-)

@fonzo14

+1

@tobi

It looks like this is being stonewalled but in an effort to keep a right idea alive here is a proposal for how to fix the situation in a way that everyone is happy:

  • Modify rubygems to no longer generate docs
  • Every time a gem is installed a new file is added to ~/.gems directory that indicates that documentation is currently out of date
  • Rubygems gets a new command called gem generate-documentation
  • Rubygems gets a new command called gem update-documentation [gem name], generates all documentation by default, does nothing if documentation is already up to date indicated by the absence of the file in ~/.gems
  • The Ri and gem server tools are modified to run gem update-documentation before executing.
@croaky

I've been helping some developers learn Rails recently. The instinct of those developers is to Google for documentation. I show them http://apirails.com and http://rubydoc.info and http://relishapp.com. It looks to me like they're actively and happily using documentation outside of the Rubygems local install docs.

Those (and other) sites, along with a desire to provide good support, provide plenty of motivation for gem authors to write documentation.

Experienced developers also don't seem to use these docs and use --no-ri and --no-rdoc in their .gemrc file. Reversing the default has positive speed implications and would make all these +1'ers happy.

@cmhobbs

Well, swimming against the tide... I happen to use rdoc and ri that's installed with gems. I frequently code offline and find it handy. Looks like I've been snowballed, but that's just fine. Just wanted to add my $0.02, whatever that's worth these days.

@jlnr

+1

ri and (local) rdoc were the first things I was taught beyond ruby and irb, and the first things I consciously forgot and later disabled. Sadly I never remember to turn it off on production servers, and the last time it caused gem installation to fail is just 6 days ago. For extra fun you should see how long doc generation can (used to?) take on JRuby.

@andyl

How can you turn off the email notifications for this chat thread ??

@pjb3

github --no-notification, can we make this the default? ;)

@pedromartinez

+1 dammit

@pedromartinez

+1 dammit

@alan
  • 1
@ippa

-1 ... just kidding, +1.

@slavat

+1

@owain68

+1

@cognition

+1 please do

@Calamitous

+1 please

@jjb

@drbrain i had no idea about gem server -- nice!

@ctcherry

+1 for sure

@colszowka

Everyone wishing they never had replied to this, try unchecking "Edit your Profile -> Notification Center -> Comments after me on commits" until the plus-one-twitter-zombies all burn in hell ;)

@rafaelp

+1

@colszowka

@hooobs: Right, you're the 1 in 100 that will want to create ~/.gemrc with "gem: --rdoc --ri" on your local machine, not in production though. This is not about removing rdoc functionality from rubygems.

@levifig

@colszowka THANK YOU!!!!!!! :)

@genezys

+1

Local documentation looks nice (just discovered it) but not worth the install time when I want to try a new gem I just found. If I want to install, there is a good chance I already found and read the online documentation.

@jjb

Here's a pull request that provides documentation for the user about ri and rdoc after installation: #44

@colszowka

Dammit, that "Comments after me on commits" notification setting doesn't help - any other ideas how to opt-out of the madness?

@justbaker

+1

I rarely read the built in documentation, and it is usually the longest part of a gem install :/.

@justbaker

+1

I rarely read the built in documentation, and it is usually the longest part of a gem install :/.

@stammy

+1

@burke

+1

Newbies don't use ri, and people who need it probably know how to build documentation from already-installed gems. If not, someone will blog about it.

Installing ri and rdoc as the default is very counter to the way most ruby developers -- especially new developers -- consume documentation, and IMHO should be opt-in.

Flat-out ignoring hundreds of votes-in-favour from users is foolish.

@postmodern

OK, you got me thinking. I threw together a rubygems plugin that adds the doc command. gem doc will generate the documentation for an installed gem, and view it using the systems browser (using Launchy). This will allow all RDoc/RI generation to be disabled, but still let users pull up local docs if/when they need them.

https://github.com/postmodern/rubygems-doc

@postmodern

OK you convinced me. +9000

RubyGems should not be doing anything with RI or RDoc. YARD appears to be the clear winner here, it runs rubydoc.info and comes with a local server:

$ gem install yard
$ yard server --gems

Need docs? Use YARD.

@cesare

+1

@n0ts

+1

@mgreenly

+1

At least 99% of the time , when I've generated docs, it was because of the default and not because I wanted them. A command to generate out of date docs and --with-rdoc / --with-ri options would be perfect.

@Bounga

+1

@JohnFord

Scroll up, guys. I think we "won". It looks like the maintainers are planning to change the way docs work. So we can stop with the +1's, thanks. (FYI it sends an email to everyone who posted above you and we've already gotten hundreds.)

@pcreux

+1

@ghazel

+1

@aziz

+1

@justbaker

This pull request is closed, please stop with the +1's! I think a hundred or so are plenty.

@radar

@justinbaker: no.

Seriously though, https://github.com/account/notifications. Uncheck "Comments on Issues after me". DONE.

@benatkin

It's closed, but not forgotten. I think perhaps the focus ought to be shifted towards getting tools people use to install rubygems to set reasonable defaults if rubygems itself won't.

Also I just clicked Reopen 50 times. I don't have permission to but it felt good. Thanks github for designing the non-working button the way you did!

@parndt

+1 justinbaker

Couldn't resist.

Honestly, It's a huge shame that this pull request has been closed as it offers one of the most significant performance increases to ruby developers who just want to get on with the job and install lots of gems without this massive overhead every. single. time.

I always thought rubygems was a tool by the ruby community for the ruby community but it seems the community has spoken and been swiftly ignored. "No correspondence will be entered into" I guess?

@scotttam

+1

@mihael

+X

@peter

+1

@jerome

+1

@williamn

+1

@wxianfeng

+1
every time i am add --no-ri --no-rdoc

@PanosJee

+1

@pklingem

+1

@brunosoab

wait +1

@jjb
jjb commented

Hey folks. I made this compromise patch which educates users how to use rdoc and ri, and how to not install them in the future. check it out! #44

@parndt

Good news, you can now unsubscribe to notifications from just this pull request. https://github.com/blog/821-mention-somebody-they-re-notified

@asanghi

This is pull number 42.

@MindTooth

You'll have my vote as well.

+1

@celeduc

+1, now more than ever.

@PikachuEXE

+1
How come this is not merged?

@PofMagicfingers

pull request closed ? but ... +1 !

@PikachuEXE

Why is it closed? Maybe GitHub bug or something
Anyway +1

@lukaseder

-1, actually

@mkristian
@sagarey

+1

This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 25, 2011
  1. @dhh
This page is out of date. Refresh to see the latest.
View
6 lib/rubygems/commands/install_command.rb
@@ -19,8 +19,8 @@ class Gem::Commands::InstallCommand < Gem::Command
def initialize
defaults = Gem::DependencyInstaller::DEFAULT_OPTIONS.merge({
- :generate_rdoc => true,
- :generate_ri => true,
+ :generate_rdoc => false,
+ :generate_ri => false,
:format_executable => false,
:version => Gem::Requirement.default,
})
@@ -39,7 +39,7 @@ def arguments # :nodoc:
end
def defaults_str # :nodoc:
- "--both --version '#{Gem::Requirement.default}' --rdoc --ri --no-force\n" \
+ "--both --version '#{Gem::Requirement.default}' --no-rdoc --no-ri --no-force\n" \
"--install-dir #{Gem.dir}"
end
View
6 lib/rubygems/commands/update_command.rb
@@ -15,8 +15,8 @@ class Gem::Commands::UpdateCommand < Gem::Command
def initialize
super 'update',
'Update the named gems (or all installed gems) in the local repository',
- :generate_rdoc => true,
- :generate_ri => true,
+ :generate_rdoc => false,
+ :generate_ri => false,
:force => false
add_install_update_options
@@ -44,7 +44,7 @@ def arguments # :nodoc:
end
def defaults_str # :nodoc:
- "--rdoc --ri --no-force --install-dir #{Gem.dir}"
+ "--no-rdoc --no-ri --no-force --install-dir #{Gem.dir}"
end
def usage # :nodoc:
View
2  lib/rubygems/install_update_options.rb
@@ -121,7 +121,7 @@ def add_install_update_options
# Default options for the gem install command.
def install_update_defaults_str
- '--rdoc --no-force --wrappers'
+ '--no-rdoc --no-force --wrappers'
end
end
Something went wrong with that request. Please try again.