Turn off ri and rdoc generation by default #42

Closed
wants to merge 1 commit into
from

Projects

None yet
@dhh
dhh commented Feb 25, 2011

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?

@nathanhoad

+1

@bjreath
bjreath commented Feb 25, 2011

+1

@vinayvinay

+1

@febuiles

+1

@ismasan
ismasan commented Feb 25, 2011

+1

@jeremyherbert

+1 please dear world please

@blahed
blahed commented Feb 25, 2011

+1

@redinger

+1

@jaredbrown

+1

@Yardboy
Yardboy commented Feb 25, 2011

+1

@jm
jm commented Feb 25, 2011

+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
kouky commented Feb 25, 2011

+1

@darrenterhune

+ten hundred million thousand... I win

@luke0x
luke0x commented on 8c70f33 Feb 25, 2011

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

+1

@paulodeleo

+1

@vanntastic

+1

@campreb
campreb commented Feb 25, 2011

+1

@rbazinet

+1

@jwilson511

+1

@andybluntish

+1

@niwat0ri

+1

@radar
radar commented Feb 25, 2011

Holy crap @ response.

+1

@radar
radar commented Feb 25, 2011

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

@jackhq
jackhq commented Feb 25, 2011

+1

@plukevdh

+1

@lewisou
lewisou commented Feb 25, 2011

+1

@trevrosen

+1

@cclow
cclow commented Feb 25, 2011

+1

@joeyw
joeyw commented Feb 25, 2011

+1

@ccollins

+1

@morexchange

+1

@benhoskings

+1

@geetarista

+1

@fjoachim

+1

@armstrjare

+1

@naudo
naudo commented Feb 25, 2011

+1

@joho
joho commented Feb 25, 2011

+1

@thorncp
thorncp commented Feb 25, 2011

yes please

@ihower
ihower commented Feb 25, 2011

+1

@databyte

+1.01

@tjmcewan

+1

@jmccartie

+1

@kossnocorp

+1

@igrigorik

+1

@nickcoyne

+1

@IanMitchell

+1

@boboroshi

+1

@leondu
leondu commented Feb 25, 2011

+1

@foxzool
foxzool commented Feb 25, 2011

+1

@xiaods
xiaods commented Feb 25, 2011

+1

@jamesmartin

+1

@ajwalters

+1

@athak
athak commented Feb 25, 2011

+1

@ghost
ghost commented Feb 25, 2011

+1

@DBA
DBA commented Feb 25, 2011

+1

@DylanFM
DylanFM commented Feb 25, 2011

+1

@benatkin

YES!

@wweidendorf

+1

@davemcp
davemcp commented Feb 25, 2011

+1

@don
don commented Feb 25, 2011

+1

@JosephKu

+1

@camfowler

+1

@zenmatt
zenmatt commented Feb 25, 2011

+1

@shairontoledo

+1 and less .files to config

@kovyrin
kovyrin commented Feb 25, 2011

+1

@stmpjmpr

+1

@cajun-code

+1

@shanepinnell

+1

@alassek
alassek commented Feb 25, 2011

+1

@apsharkey

+1

@plentz
plentz commented Feb 25, 2011

+1

@samgranieri

+1 FTW!

@sikachu
sikachu commented Feb 25, 2011

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

@drbrain
Member
drbrain commented Feb 25, 2011

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

See gem help env for details.

@levifig
levifig commented Feb 25, 2011

Yes, please!!!

@fmeyer
fmeyer commented Feb 25, 2011

+1

@larryhbn

+1

@ryanrray

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

@marcusp
marcusp commented Feb 25, 2011

+1

@srbaker
srbaker commented Feb 25, 2011

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.

@jbancroft

+1

@capotej
capotej commented Feb 25, 2011

+1

@tikhon
tikhon commented Feb 25, 2011

+1

@amerine
amerine commented Feb 25, 2011

@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
eploko commented Feb 25, 2011

+1

@heffay
heffay commented Feb 25, 2011

+1 !!!!

@JohnFord

+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
fbjork commented Feb 25, 2011

+1

@rubysolo

+1

@brandonweiss

+1

@andyl
andyl commented Feb 25, 2011

+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
@railsfactory

+1

@uilgenstein

+1

@leandro
leandro commented Feb 25, 2011

+1! I always wanted that.

@crossforward

+1

@marcoemrich

+1

@rbialek
rbialek commented Feb 25, 2011

+1

@libo
libo commented Feb 25, 2011

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
fonzo14 commented Feb 25, 2011

+1

@tobi
tobi commented Feb 25, 2011

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
croaky commented Feb 25, 2011

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
cmhobbs commented Feb 25, 2011

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.

@cnicolaou

+1

@jlnr
jlnr commented Feb 25, 2011

+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
andyl commented Feb 25, 2011

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

@bhauman
bhauman commented Feb 25, 2011
  • 1
@pjb3
pjb3 commented Feb 25, 2011

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

@pedromartinez

+1 dammit

@pedromartinez

+1 dammit

@alan
alan commented Feb 25, 2011
  • 1
@ippa
ippa commented Feb 25, 2011

-1 ... just kidding, +1.

@nerdyworm

+1

@slavat
slavat commented Feb 25, 2011

+1

@jasonong

+1

@owain68
owain68 commented Feb 25, 2011

+1

@cognition

+1 please do

@Calamitous

+1 please

@jjb
jjb commented Feb 25, 2011

@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
rafaelp commented Feb 25, 2011

+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
levifig commented Feb 25, 2011

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

@genezys
genezys commented Feb 25, 2011

+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
jjb commented Feb 25, 2011

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

@rubystream

+1

@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
stammy commented Feb 25, 2011

+1

@burke
burke commented Feb 25, 2011

+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
cesare commented Feb 26, 2011

+1

@n0ts
n0ts commented Feb 26, 2011

+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
Bounga commented Feb 26, 2011

+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
pcreux commented Feb 28, 2011

+1

@dminchev

+1

@ghazel
ghazel commented Mar 1, 2011

+1

@aziz
aziz commented Mar 2, 2011

+1

@justbaker

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

@radar
radar commented Mar 2, 2011

@justinbaker: no.

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

@benatkin
benatkin commented Mar 2, 2011

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
parndt commented Mar 2, 2011

+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?

@apneadiving

+1

@scotttam
scotttam commented Mar 3, 2011

+1

@mihael
mihael commented Mar 3, 2011

+X

@peter
peter commented Mar 3, 2011

+1

@buffpojken

+1

@asiazhang

+1

@dstockdale

+1

@jerome
jerome commented Mar 3, 2011

+1

@hugobarauna

+1

@hugobarauna

+1

@tatygrassini

+1

@williamn
williamn commented Mar 4, 2011

+1

@wxianfeng

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

@PanosJee
PanosJee commented Mar 4, 2011

+1

@pklingem
pklingem commented Mar 4, 2011

+1

@mandelbroat

wait +1

@jmonteiro

+1

@jjb
jjb commented Mar 9, 2011

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

@burningTyger

+1

@codatory

+1

@rickthomasjr

+1

@parndt
parndt commented Mar 23, 2011

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

@asanghi
asanghi commented Mar 27, 2011

This is pull number 42.

@sawanoboly

+1

@MindTooth

You'll have my vote as well.

+1

@charliesome

+1

@celeduc
celeduc commented Sep 14, 2012

+1, now more than ever.

@xfstart07

+1

@garethrees

+1

@PikachuEXE

+1
How come this is not merged?

@lukaselmer

+1

@araipiyo

+1

@mkristian

+1

@PofMagicfingers

pull request closed ? but ... +1 !

@PikachuEXE

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

@lukaseder

-1, actually

@mkristian

very much +1
we use this default with jruby already ;)

@sagarey
sagarey commented Jan 19, 2015

+1

This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment