Please review pull request #572: 2.7.x: rdoc vs ruby 1.9.3 opened by (daniel-pittman)
Description:
Ruby 1.9 changed the core version of RDoc, which makes our integration with it for documentation generation blow up. In fact, since the internal library layout changed, we blow up horribly trying to require files that could never work in newer versions.
This series of changes updates Puppet to recognise that we only support RDoc 1.*, and to disable documentation generation with RDoc for anything other than that version of the library.
This means that 1.9 now correctly and cleanly fails when asked to use RDoc, rather than blowing up with horrible internal errors, and we generally have a better user experience.
- Opened: Fri Mar 09 22:08:47 UTC 2012
- Based on: puppetlabs:2.7.x (b01088d112010452942b425c15894036bdea8a83)
- Requested merge: daniel-pittman:maint/2.7.x/rdoc-vs-ruby-1.9.3 (62a453317eb7eff587284d4fab75b5fb55dd2818)
Diff follows:
diff --git a/lib/puppet/application/doc.rb b/lib/puppet/application/doc.rb
index d2683b0..daf7595 100644
--- a/lib/puppet/application/doc.rb
+++ b/lib/puppet/application/doc.rb
@@ -60,6 +60,8 @@ def help
Generates a reference for all Puppet types. Largely meant for internal
Puppet Labs use.
+WARNING: RDoc support is only available under Ruby 1.8.7 and earlier.
+
USAGE
-----
@@ -83,6 +85,11 @@ def help
If the command is run with the name of a manifest file as an argument,
puppet doc will output a single manifest's documentation on stdout.
+WARNING: RDoc support is only available under Ruby 1.8.7 and earlier.
+The internal API used to support manifest documentation has changed
+radically in newer versions, and support is not yet available for
+using those versions of RDoc.
+
OPTIONS
-------
diff --git a/lib/puppet/feature/rdoc1.rb b/lib/puppet/feature/rdoc1.rb
new file mode 100644
index 0000000..a7e65c2
--- /dev/null
+++ b/lib/puppet/feature/rdoc1.rb
@@ -0,0 +1,16 @@
+require 'puppet/util/feature'
+
+# We have a version of RDoc compatible with our module documentation tool.
+# That is to say, we have the version that comes with Ruby 1.8.7 and earlier,
+# and not the version that comes with Ruby 1.9.1 or later.
+#
+# 1.8 => require 'rdoc/rdoc'; p RDoc::RDoc::VERSION_STRING
+# => "RDoc V1.0.1 - 20041108"
+# 1.9 => require 'rdoc'; p RDoc::VERSION
+# => "3.9.4" # 1.9.2 has 2.5, 1.9.3 has 3.9
+#
+# Anything above that whole 1.0.1 thing is no good for us, and since that
+# ships with anything in the 1.8 series that we care about (eg: .5, ,7) we can
+# totally just use that as a proxy for the correct version of rdoc being
+# available. --daniel 2012-03-08
+Puppet.features.add(:rdoc1) { RUBY_VERSION[0,3] == "1.8" }
diff --git a/lib/puppet/util/rdoc.rb b/lib/puppet/util/rdoc.rb
index c00bc6f..fe1a3c5 100644
--- a/lib/puppet/util/rdoc.rb
+++ b/lib/puppet/util/rdoc.rb
@@ -1,11 +1,15 @@
-
+require 'puppet/util'
module Puppet::Util::RDoc
-
module_function
# launch a rdoc documenation process
# with the files/dir passed in +files+
def rdoc(outputdir, files, charset = nil)
+ unless Puppet.features.rdoc1?
+ raise "the version of RDoc included in Ruby #{::RUBY_VERSION} is not supported"
+ end
+
+ begin
Puppet[:ignoreimport] = true
# then rdoc
@@ -18,25 +22,26 @@ def rdoc(outputdir, files, charset = nil)
r = RDoc::RDoc.new
RDoc::RDoc::GENERATORS["puppet"] = RDoc::RDoc::Generator.new(
- "puppet/util/rdoc/generators/puppet_generator.rb",
- "PuppetGenerator".intern,
- "puppet")
+ "puppet/util/rdoc/generators/puppet_generator.rb",
+ :PuppetGenerator,
+ "puppet"
+ )
# specify our own format & where to output
options = [ "--fmt", "puppet",
- "--quiet",
- "--exclude", "/modules/[^/]*/files/.*\.pp$",
- "--op", outputdir ]
+ "--quiet",
+ "--exclude", "/modules/[^/]*/files/.*\.pp$",
+ "--op", outputdir ]
options << "--force-update" if Options::OptionList.options.any? { |o| o[0] == "--force-update" }
options += [ "--charset", charset] if charset
options += files
- #TODO dedup file paths (not strict duplication sense, parents, children, etc
# launch the documentation process
r.document(options)
- rescue RDoc::RDocError => e
+ rescue RDoc::RDocError => e
raise Puppet::ParseError.new("RDoc error #{e}")
+ end
end
# launch a output to console manifest doc
@@ -82,5 +87,4 @@ def output_resource_doc(code)
end
end
end
-
end
diff --git a/spec/integration/application/doc_spec.rb b/spec/integration/application/doc_spec.rb
index 2cf5fd1..223824e 100755
--- a/spec/integration/application/doc_spec.rb
+++ b/spec/integration/application/doc_spec.rb
@@ -5,7 +5,7 @@
describe Puppet::Application::Doc do
include PuppetSpec::Files
- it "should not generate an error when module dir overlaps parent of site.pp (#4798)", :'fails_on_ruby_1.9.2' => true, :unless => Puppet.features.microsoft_windows? do
+ it "should not generate an error when module dir overlaps parent of site.pp (#4798)", :if => Puppet.features.rdoc1?, :unless => Puppet.features.microsoft_windows? do
begin
# Note: the directory structure below is more complex than it
# needs to be, but it's representative of the directory structure
diff --git a/spec/integration/util/rdoc/parser_spec.rb b/spec/integration/util/rdoc/parser_spec.rb
index bf1f0d2..90dab74 100755
--- a/spec/integration/util/rdoc/parser_spec.rb
+++ b/spec/integration/util/rdoc/parser_spec.rb
@@ -1,17 +1,19 @@
#!/usr/bin/env rspec
require 'spec_helper'
-require 'puppet/resource/type_collection'
-require 'puppet/util/rdoc/parser'
-require 'puppet/util/rdoc'
-require 'puppet/util/rdoc/code_objects'
-require 'rdoc/options'
-require 'rdoc/rdoc'
-
-describe RDoc::Parser, :'fails_on_ruby_1.9.2' => true do
+describe "RDoc::Parser", :if => Puppet.features.rdoc1? do
require 'puppet_spec/files'
include PuppetSpec::Files
+ before :all do
+ require 'puppet/resource/type_collection'
+ require 'puppet/util/rdoc/parser'
+ require 'puppet/util/rdoc'
+ require 'puppet/util/rdoc/code_objects'
+ require 'rdoc/options'
+ require 'rdoc/rdoc'
+ end
+
before :each do
tmpdir = tmpfile('rdoc_parser_tmp')
Dir.mkdir(tmpdir)
diff --git a/spec/unit/util/rdoc/parser_spec.rb b/spec/unit/util/rdoc/parser_spec.rb
index f958730..c24adf7 100755
--- a/spec/unit/util/rdoc/parser_spec.rb
+++ b/spec/unit/util/rdoc/parser_spec.rb
@@ -1,13 +1,15 @@
#!/usr/bin/env rspec
require 'spec_helper'
-require 'puppet/resource/type_collection'
-require 'puppet/util/rdoc/parser'
-require 'puppet/util/rdoc/code_objects'
-require 'rdoc/options'
-require 'rdoc/rdoc'
+describe "RDoc::Parser", :if => Puppet.features.rdoc1? do
+ before :all do
+ require 'puppet/resource/type_collection'
+ require 'puppet/util/rdoc/parser'
+ require 'puppet/util/rdoc/code_objects'
+ require 'rdoc/options'
+ require 'rdoc/rdoc'
+ end
-describe RDoc::Parser, :'fails_on_ruby_1.9.2' => true do
include PuppetSpec::Files
before :each do
diff --git a/spec/unit/util/rdoc_spec.rb b/spec/unit/util/rdoc_spec.rb
index deae4ef..93e5d0e 100755
--- a/spec/unit/util/rdoc_spec.rb
+++ b/spec/unit/util/rdoc_spec.rb
@@ -5,8 +5,14 @@
require 'rdoc/rdoc'
describe Puppet::Util::RDoc do
+ it "should fail with a clear error without RDoc 1.*" do
+ Puppet.features.stubs(:rdoc1?).returns(false)
- describe "when generating RDoc HTML documentation", :'fails_on_ruby_1.9.2' => true do
+ expect { Puppet::Util::RDoc.rdoc("output", []) }.
+ should raise_error(/the version of RDoc .* is not supported/)
+ end
+
+ describe "when generating RDoc HTML documentation", :if => Puppet.features.rdoc1? do
before :each do
@rdoc = stub_everything 'rdoc'
RDoc::RDoc.stubs(:new).returns(@rdoc)
@@ -14,7 +20,6 @@
it "should tell the parser to ignore import" do
Puppet.expects(:[]=).with(:ignoreimport, true)
-
Puppet::Util::RDoc.rdoc("output", [])
end
-- You received this message because you are subscribed to the Google Groups "Puppet Developers" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to [email protected].
For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en.
