Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

ri and rdoc take a long time, don't include them by default. #3

Open
wants to merge 1 commit into from
@jeffrafter

Turn off ri and rdoc generation as defaults, from @dhh with passing tests, http://bit.ly/lsvXWv

See also rubygems/rubygems#42 for one of the most famous github pull requests of all time.

@nate

+9001 (OVER 9000!)

@Sutto

I like the idea of ri generation (although I don't necessarily use it for gems), but I like the idea of instead using on-demand doc generation for rdocs (Or, you know, yard ;)). (+1, but I didn't want to be a dick about it)

@rahult

+1, makes sense, by default ri and rdoc are disabled in my gemrc file so I can generate documentation for specific projects

@lsegal
Owner

There's definitely a lot of user consensus around this issue. That's a good thing. But I think the consensus is based on the fact that this is a huge performance / efficiency bottleneck in the install process, not the fact that documentation is not warranted.

I think there's another way to go about this issue that improves performance substantially but also still manages to provide documentation to users. I've previously proposed on the rubygems mailing list (here) that we can allow gem maintainers to push up static .html versions of their documentation to the web (via gem push_docs). A gem install would then look for the presence of these packages and download them if available. If not, it would fall back on local generation (or perhaps --no-rdoc should be default in the fallback case). The download would be slightly heavier, but the install would be effectively instantaneous, and not take up enough CPU % to power a lightbulb for a day. I see this as a pretty effective compromise, encouraging gem developers to provide documentation while making the install process much faster. An added benefit of such a feature would mean that maintainers could write docs using whatever tool they wanted: rdoc, yard, rocco, tomdoc, jekyll, or even simple hand crafted HTML. Because the docs are static, the entire question of "which tool works best with RubyGems?" is completely removed from the equation. It gives freedom to maintainers, it gives performance to users, and it encourages documentation.

Am I wrong? Do people really just want to avoid local docs altogether?

@rahult

Hmm, never thought about it in this way. This is a much better solution; it is way easier for gem maintainers to push docs as most of the time they generate docs for testing and reviewing no matter what. Also you right, this will greatly increase the install speed of gems with proper documentation (just bringing in compressed packaged doc files).

Personally, I always want local documentation as it fits really well with emacs and I can look at it without being online or going to a third party service.

(+1)

@nashby

+1
Seriously, who are still using the local documentation?

@tilsammans

@lsegal, that is actually a great solution. My concern with generating the docs by default is in fact that it takes ages. I am not opposed to documentation per se, although I personally never read it.

Would you not agree that docs on the server are never useful though? We might consider adding a "--deployment" flag (no off-topic Bundler arguments please) that sets an appropriate deployment environment, skipping docs and whatnot?

@mkristian

ever since I found out that --no-rdoc can be configured system wide, I use
$ cat ~/.gemrc
install: --no-ri --no-rdoc
update: --no-ri --no-rdoc

so I have to admit that I do not read docs online or offline - I am usually happy with reading the code and if available the docu in it.

the idea of separating the code from the documentation into two "packages" is very familiar to me since that is the way things are done in "some parts of the java world - maven". so tools and/or people can download and install the documentation with a second package. translated into the rubyworld it would be something like

$ gem install yard
for the code and for the docs
$ gem install --docs yard
maybe the later does install the code as well if not there.

(+1) for skipping docu per default and have a way of getting the docs when I really want/need them.

@nirvdrum

@lsegal I think that's a valid compromise. I now use the yard server for local docs, but even that can be heavy to run. Statically generated docs make a ton of sense and seems to be what every other community does.

@bcardarella

@lsegal I'm with @nirvdrum makes sense, +1

@lsegal
Owner

@tilsammans, yes, that sounds reasonable. In this case --deployment would turn on the hypothetical --no-fetch-docs (not the actual name yet) as well as turn on --no-rdoc for local builds. Although, it would be nice to do this all with --no-rdoc alone.

@trans

There is always this approach too:

rubygems/rubygems#16

i.e. leave it to the documentation server itself.

@trans

And option 3, just put the docs in doc/ and distribute them in the package. Seriously is a few 100K that big anymore?

@jeffrafter

I really like the on-demand patch, I think that is a great solution. A few hundred K is not so much for one gem, but when bundler installs 40 gems at a time that will add some delay.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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,
:test => false,
:version => Gem::Requirement.default,
@@ -40,7 +40,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" \
"--no-test --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,
:test => false
@@ -45,7 +45,7 @@ def arguments # :nodoc:
end
def defaults_str # :nodoc:
- "--rdoc --ri --no-force --no-test --install-dir #{Gem.dir}"
+ "--no-rdoc --no-ri --no-force --no-test --install-dir #{Gem.dir}"
end
def usage # :nodoc:
View
2  lib/rubygems/install_update_options.rb
@@ -118,7 +118,7 @@ def add_install_update_options
# Default options for the gem install command.
def install_update_defaults_str
- '--rdoc --no-force --no-test --wrappers'
+ '--no-rdoc --no-ri --no-force --no-test --wrappers'
end
end
View
4 test/test_gem_command_manager.rb
@@ -55,7 +55,7 @@ def test_process_args_install
#check defaults
@command_manager.process_args("install")
assert_equal false, check_options[:test]
- assert_equal true, check_options[:generate_rdoc]
+ assert_equal false, check_options[:generate_rdoc]
assert_equal false, check_options[:force]
assert_equal :both, check_options[:domain]
assert_equal true, check_options[:wrappers]
@@ -192,7 +192,7 @@ def test_process_args_update
#check defaults
@command_manager.process_args("update")
- assert_equal true, check_options[:generate_rdoc]
+ assert_equal false, check_options[:generate_rdoc]
#check settings
check_options = nil
View
14 test/test_gem_commands_update_command.rb
@@ -5,7 +5,7 @@ class TestGemCommandsUpdateCommand < RubyGemTestCase
def setup
super
-
+
@oldpath = Dir.pwd
Dir.chdir(File.dirname(__FILE__))
@@ -26,12 +26,12 @@ def setup
@fetcher.data["#{@gem_repo}gems/#{@a2.file_name}"] =
read_binary @a2_path
end
-
+
def teardown
super
Dir.chdir(@oldpath)
end
-
+
def test_execute
util_clear_gems
@@ -318,11 +318,11 @@ def test_handle_options_system
@cmd.handle_options %w[--system]
expected = {
- :generate_ri => true,
+ :generate_ri => false,
:system => true,
:force => false,
:args => [],
- :generate_rdoc => true,
+ :generate_rdoc => false,
:test => false,
}
@@ -339,11 +339,11 @@ def test_handle_options_system_specific
@cmd.handle_options %w[--system 1.3.7]
expected = {
- :generate_ri => true,
+ :generate_ri => false,
:system => "1.3.7",
:force => false,
:args => [],
- :generate_rdoc => true,
+ :generate_rdoc => false,
:test => false,
}
Something went wrong with that request. Please try again.