Turn off ri and rdoc generation by default #42

Closed
wants to merge 1 commit into
from

Projects

None yet
@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 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

+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

@ghost

+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
RubyGems member

~/.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

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

@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