Skip to content
This repository

Turn off ri and rdoc generation by default #42

Closed
wants to merge 1 commit into from

291 participants

David Heinemeier Hansson

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?

Brian J Reath

+1

Ismael Celis

+1

Jeremy Herbert

+1 please dear world please

Travis Dunn

+1

Cayce Balara

+1

Jeremy McAnally
jm commented

+1 definitely.

Mario Visic

+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).

Michael Koukoullis

+1

Darren Terhune

+ten hundred million thousand... I win

Luke Crawford

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

Cameron Prebble

+1

Ryan Bigg

Holy crap @ response.

+1

Ryan Bigg

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

Jack Russell Software Company

+1

Lewisou

+1

Low Chin Chau

+1

Joey Wendt

+1

Nicholas Audo

+1

John Barton

+1

Chris Thorn

yes please

Wen-Tien Chang

+1

David Sommers

+1.01

Leon Du

+1

ZoOL

+1

Deshi Xiao

+1

Atha Kouroussis

+1

Diogo Almeida

+1

Dylan Fogarty-MacDonald

+1

benatkin

YES!

davemcp

+1

Don Coleman

+1

Matt Tanase

+1

Shairon Toledo

+1 and less .files to config

Oleksiy Kovyrin

+1

Adam Lassek

+1

Diego Plentz

+1

Sam Granieri

+1 FTW!

Prem Sichanugrist

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

Eric Hodel
Owner

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

See gem help env for details.

Levi Figueira

Yes, please!!!

F. Meyer

+1

Ryan

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

marcusp

+1

Steven R. Baker

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.

Julio Capote

+1

Tikhon Bernstam

+1

Mark Turner

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

Andrey Subbotin

+1

Geoff Parris

+1 !!!!

Brandon Hays

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

Jack Danger Canty

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

Fredrik Björk

+1

Gregory Graf

+1

Jason Decker

+1

Nihad Abbasov

+1

Eric Hodel
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.

John Barton

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

TaopaiC

+1

Barry Hess

+1

Federico Builes

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

Levi Figueira

@febuiles hit the right argument!

Roger Nesbitt

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

Kai Janson

+1

kfir

+1

Nathan Howell

+1

Sean Carey

+1

Paul Barry

+1

Tim Gildea

+1

Deleted user

The content you are editing has changed. Reload the page and try again.

+1

Sending Request…

Attach images by dragging & dropping or selecting them. Octocat-spinner-32 Uploading your images… Unfortunately, we don't support that file type. Try again with a PNG, GIF, or JPG. Yowza, that's a big file. Try again with an image file smaller than 10MB. This browser doesn't support image attachments. We recommend updating to the latest Internet Explorer, Google Chrome, or Firefox. Something went really wrong, and we can't process that image. Try again.

Eric Woodward

+1

David Safar

+1

PJ Davis

+1

Doug Renn

+1

Eric Hodel
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.

Jim Ruther Nill

+1

Adrian Wisernig

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

Doug Renn

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

Philip Arndt

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.

Andro Salinas

+1

Kevin R. Barnes

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

Karuna Murti

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

Brandon Tilley

Can we +2?

Matthew Rudy Jacobs

+1 for sure!

Joey Lin

+1

Berislav Babic

+1

Christoph Klocker

+1

Brian Moelk

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

Nick Ragaz

+1

Preston Marshall

Please

Christoph Olszowka

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. :)

Steven R. Baker

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

Jack Danger Canty

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

Scott 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."

Martin Andert

+1

Raphaël Emourgeon

+1

Joel Westerberg

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".

Richard Wöber

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

James Tucker
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

Umit Kayacik

+1

Max Mack

+1

Lukáš Konarovský

+1

Jack Danger Canty

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

Eugene Brechko

+1

Jeremy Nicoll

+1 x 10000000000000000000000000000000000000!

Zeno R.R. Davatz

+1 extra

Preston Marshall

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

Matthew Rudy Jacobs

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

Paul Campbell

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

Wes Oldenbeuving

+1

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

Yuanyi Zhang

+1

Lucas Andión Montáns

+1

Max Riveiro

+1
Count me in, too.

Alex Ganov

+1

Sebastian

+1

Maik Schmidt

+1

Igor Sidorov

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

Delwyn de Villiers

+1

Alexander Petrov

+1

Alexandre Gherschon

+1

+1

Joost Baaij

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

Kasper Weibel Nielsen-Refs

+1

Will Jessop

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

Scott Gonyea

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.

Ben Hayman

+1

Scott Gonyea

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

Alessandro Dal Grande

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

Jérémy Pinat

+1

Christoph Olszowka

Dammit, how do I unsubscribe from this??

Taylor luk

+1 oh yeah

Libo Cannici

+1

Kent Fenwick

+1

Edgardo Rossetto

+1

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

Jérémy Lecour

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

Pablo Corral

+1

Deleted user

The content you are editing has changed. Reload the page and try again.

+1

Sending Request…

Attach images by dragging & dropping or selecting them. Octocat-spinner-32 Uploading your images… Unfortunately, we don't support that file type. Try again with a PNG, GIF, or JPG. Yowza, that's a big file. Try again with an image file smaller than 10MB. This browser doesn't support image attachments. We recommend updating to the latest Internet Explorer, Google Chrome, or Firefox. Something went really wrong, and we can't process that image. Try again.

Shalva Usubov

+1

Nicholas Rutherford

+1

andyl

+1

Denny Abraham

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 Camargo

+1! I always wanted that.

Robert Bialek

+1

Libo Cannici

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

Tobias Lütke

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.
Dan Croak

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.

Christopher M. Hobbs

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.

Julian Raschke

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

Paul Barry

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

Pedro Martinez

+1 dammit

Pedro Martinez

+1 dammit

Alan Kennedy
  • 1
ippa

-1 ... just kidding, +1.

Viachaslau Tysianchuk

+1

Owain McGuire

+1

Ramon Brooker

+1 please do

Eric Budd

+1 please

John Bachir

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

Chris Cherry

+1 for sure

Christoph Olszowka

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 ;)

Rafael Lima

+1

Christoph Olszowka

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

Levi Figueira

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

Vincent Robert

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

John Bachir

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

Christoph Olszowka

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

Justin Baker

+1

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

Justin Baker

+1

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

Paul Stamatiou

+1

Burke Libbey

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

SAWADA Tadashi

+1

Naoya Nakazawa

+1

Michael Greenly

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

Nicolas Cavigneaux

+1

John Ford

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.)

Philippe Creux

+1

Greg Hazel

+1

Allen Bargi
aziz commented

+1

Justin Baker

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

Ryan Bigg
radar commented

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

Philip Arndt

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

Scott Tamosunas

+1

Miha Plohl

+X

Peter Marklund
peter commented

+1

buffpojken

+1

AsiaZhang.ZhangHeng

+1

Dom Stockdale

+1

Jérôme Lipowicz

+1

William Notowidagdo

+1

xianfeng wang

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

Panayiotis Papadopoulos

+1

Patrick Klingemann

+1

Bruno S. Barros

wait +1

Julio Monteiro

+1

John Bachir
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

Alex Conner

+1

Philip Arndt

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

Aditya Sanghi

This is pull number 42.

sawanoboly

+1

Birger J. Nordølum

You'll have my vote as well.

+1

Chuck LeDuc Díaz

+1, now more than ever.

PikachuEXE

+1
How come this is not merged?

Lukas Elmer

+1

Shunichi Arai

+1

Christian Meier

+1

PofMagicfingers

pull request closed ? but ... +1 !

PikachuEXE

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

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

Showing 1 unique commit by 1 author.

Feb 24, 2011
David Heinemeier Hansson Turn off ri and rdoc generation as defaults 8c70f33
This page is out of date. Refresh to see the latest.
6  lib/rubygems/commands/install_command.rb
@@ -19,8 +19,8 @@ class Gem::Commands::InstallCommand < Gem::Command
19 19
 
20 20
   def initialize
21 21
     defaults = Gem::DependencyInstaller::DEFAULT_OPTIONS.merge({
22  
-      :generate_rdoc     => true,
23  
-      :generate_ri       => true,
  22
+      :generate_rdoc     => false,
  23
+      :generate_ri       => false,
24 24
       :format_executable => false,
25 25
       :version           => Gem::Requirement.default,
26 26
     })
@@ -39,7 +39,7 @@ def arguments # :nodoc:
39 39
   end
40 40
 
41 41
   def defaults_str # :nodoc:
42  
-    "--both --version '#{Gem::Requirement.default}' --rdoc --ri --no-force\n" \
  42
+    "--both --version '#{Gem::Requirement.default}' --no-rdoc --no-ri --no-force\n" \
43 43
     "--install-dir #{Gem.dir}"
44 44
   end
45 45
 
6  lib/rubygems/commands/update_command.rb
@@ -15,8 +15,8 @@ class Gem::Commands::UpdateCommand < Gem::Command
15 15
   def initialize
16 16
     super 'update',
17 17
           'Update the named gems (or all installed gems) in the local repository',
18  
-      :generate_rdoc => true,
19  
-      :generate_ri   => true,
  18
+      :generate_rdoc => false,
  19
+      :generate_ri   => false,
20 20
       :force         => false
21 21
 
22 22
     add_install_update_options
@@ -44,7 +44,7 @@ def arguments # :nodoc:
44 44
   end
45 45
 
46 46
   def defaults_str # :nodoc:
47  
-    "--rdoc --ri --no-force --install-dir #{Gem.dir}"
  47
+    "--no-rdoc --no-ri --no-force --install-dir #{Gem.dir}"
48 48
   end
49 49
 
50 50
   def usage # :nodoc:
2  lib/rubygems/install_update_options.rb
@@ -121,7 +121,7 @@ def add_install_update_options
121 121
   # Default options for the gem install command.
122 122
 
123 123
   def install_update_defaults_str
124  
-    '--rdoc --no-force --wrappers'
  124
+    '--no-rdoc --no-force --wrappers'
125 125
   end
126 126
 
127 127
 end
Commit_comment_tip

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.