Intermediate commit of more reference work, including making provider suitable more introspectable. I am about to significantly change the output format of the providers reference, so i want to get this committed before that change.

git-svn-id: https://reductivelabs.com/svn/puppet/trunk@2485 980ebf18-57e1-0310-9a29-db15c13687c0

bin/puppetdoc

@@ -52,6 +52,7 @@ require 'getoptlong'
 result = GetoptLong.new(
 	[ "--all",	"-a",			GetoptLong::NO_ARGUMENT ],
 	[ "--list",	"-l",			GetoptLong::NO_ARGUMENT ],
+	[ "--format",	"-f",			GetoptLong::REQUIRED_ARGUMENT ],
 	[ "--mode",	"-m",			GetoptLong::REQUIRED_ARGUMENT ],
 	[ "--reference",	"-r",			GetoptLong::REQUIRED_ARGUMENT ],
 	[ "--help",		"-h",			GetoptLong::NO_ARGUMENT ]
@@ -60,7 +61,7 @@ result = GetoptLong.new(
 debug = false
 
 $tab = "    "
-options = {:references => [], :mode => :text}
+options = {:references => [], :mode => :text, :format => :to_rest}
 
 Reference = Puppet::Util::Reference
 
@@ -69,6 +70,13 @@ begin
         case opt
             when "--all"
                 options[:all] = true
+            when "--format"
+                method = "to_%s" % arg
+                if Reference.method_defined?(method)
+                    options[:format] = method
+                else
+                    raise "Invalid output format %s" % arg
+                end
             when "--mode"
                 if Reference.modes.include?(arg)
                     options[:mode] = arg.intern
@@ -114,15 +122,22 @@ when :trac
         end
     end
 else
-    text = ".. contents:: :depth: 1\n\n"
+    text = ""
+    if options[:references].length > 1
+        with_contents = false
+    else
+        with_contents = true
+    end
     options[:references].sort { |a,b| a.to_s <=> b.to_s }.each do |name|
         section = Puppet::Util::Reference.reference(name)
 
         # Add the per-section text, but with no ToC
-        text += section.to_rest(false)
+        text += section.send(options[:format], with_contents)
     end
 
-    text += Puppet::Util::Reference.footer
+    unless with_contents # We've only got one reference
+        text += Puppet::Util::Reference.footer
+    end
 
     # Replace the trac links, since they're invalid everywhere else
     text.gsub!(/`\w+\s+([^`]+)`:trac:/) { |m| $1 }

lib/puppet/provider.rb

@@ -179,28 +179,39 @@ class Puppet::Provider
     end
 
     # Check whether this implementation is suitable for our platform.
-    def self.suitable?
+    def self.suitable?(short = true)
         # A single false result is sufficient to turn the whole thing down.
         # We don't return 'true' until the very end, though, so that every
         # confine is tested.
+        missing = {}
         @confines.each do |check, values|
             case check
             when :exists:
                 values.each do |value|
                     unless value and FileTest.exists? value
                         debug "Not suitable: missing %s" % value
-                        return false
+                        return false if short
+                        missing[:exists] ||= []
+                        missing[:exists] << value
                     end
                 end
             when :true:
                 values.each do |v|
                     debug "Not suitable: false value"
-                    return false unless v
+                    unless v
+                        return false if short
+                        missing[:true] ||= 0
+                        missing[:true] += 1
+                    end
                 end
             when :false:
                 values.each do |v|
                     debug "Not suitable: true value"
-                    return false if v
+                    if v and short
+                        return false if short
+                        missing[:false] ||= 0
+                        missing[:false] += 1
+                    end
                 end
             else # Just delegate everything else to facter
                 if result = Facter.value(check)
@@ -211,15 +222,23 @@ class Puppet::Provider
                     end
                     unless found
                         debug "Not suitable: %s not in %s" % [check, values]
-                        return false
+                        return false if short
+                        missing[:facter] ||= {}
+                        missing[:facter][check] = values
                     end
                 else
-                    return false
+                    return false if short
+                    missing[:facter] ||= {}
+                    missing[:facter][check] = values
                 end
             end
         end
 
-        return true
+        if short
+            return true
+        else
+            return missing
+        end
     end
 
     # Does this provider support the specified parameter?

lib/puppet/reference/providers.rb

@@ -1,5 +1,5 @@
 # This doesn't get stored in trac, since it changes every time.
-providers = Puppet::Util::Reference.newreference :providers, :dynamic => true, :doc => "Which providers are valid for this machine" do
+providers = Puppet::Util::Reference.newreference :providers, :depth => 1, :dynamic => true, :doc => "Which providers are valid for this machine" do
     types = []
     Puppet::Type.loadall
     Puppet::Type.eachtype do |klass|
@@ -8,9 +8,22 @@ providers = Puppet::Util::Reference.newreference :providers, :dynamic => true, :
     end
     types.sort! { |a,b| a.name.to_s <=> b.name.to_s }
 
-    ret = ""
+    unless ARGV.empty?
+        types.reject! { |type| ! ARGV.include?(type.name.to_s) }
+    end
+
+    ret = "Details about this host:\n\n"
+
+    # Throw some facts in there, so we know where the report is from.
+    ["Ruby Version", "Puppet Version", "Operating System", "Operating System Release"].each do |label|
+        name = label.gsub(/\s+/, '')
+        value = Facter.value(name)
+        ret += option(label, value)
+    end
+    ret += "\n"
     types.each do |type|
-        ret += h(type.name, 2)
+        ret += h(type.name.to_s + "_", 2)
+        ret += ".. _%s: %s\n\n" % [type.name, "http://reductivelabs.com/trac/puppet/wiki/TypeReference#%s" % type.name]
         features = type.features
         unless features.empty?
             ret += option("Available Features", features.collect { |f| f.to_s }.sort.join(", "))
@@ -23,10 +36,25 @@ providers = Puppet::Util::Reference.newreference :providers, :dynamic => true, :
             unless features.empty?
                 ret += option(:features, provider.features.collect { |a| a.to_s }.sort.join(", "))
             end
-            if provider.suitable?
+            if missing = provider.suitable?(false) and missing.empty?
                 ret += option(:suitable?, "true")
             else
                 ret += option(:suitable?, "false")
+                ret += "\n" # must add a blank line before the list
+                missing.each do |test, values|
+                    case test
+                    when :exists:
+                        ret += "- Missing files %s\n" % values.join(", ")
+                    when :facter:
+                        values.each do |name, facts|
+                            ret += "- Fact %s (currently %s) not in list %s\n" % [name, Facter.value(name).inspect, facts.join(", ")]
+                        end
+                    when :true:
+                        ret += "- Got %s true tests that should have been false\n" % values
+                    when :false:
+                        ret += "- Got %s false tests that should have been true\n" % values
+                    end
+                end
             end
             ret += "\n" # add a trailing newline
         end

lib/puppet/util/reference.rb

@@ -131,6 +131,11 @@ class Puppet::Util::Reference
         return str
     end
 
+    # Remove all trac links.
+    def strip_trac(text)
+        text.gsub(/`\w+\s+([^`]+)`:trac:/) { |m| $1 }
+    end
+
     def text
         puts output
     end
@@ -140,7 +145,7 @@ class Puppet::Util::Reference
         text = h(@title, 1)
         text += "\n\n**This page is autogenerated; any changes will get overwritten**\n\n"
         if withcontents
-        text +=  ".. contents:: :depth: %s\n\n" % @depth
+            text +=  ".. contents:: :depth: %s\n\n" % @depth
         end
 
         text += @header
@@ -154,8 +159,12 @@ class Puppet::Util::Reference
         return text
     end
 
-    def to_trac
-        "{{{\n#!rst\n#{self.to_rest}\n}}}"
+    def to_text(withcontents = true)
+        strip_trac(to_rest(withcontents))
+    end
+
+    def to_trac(with_contents = true)
+        "{{{\n#!rst\n#{self.to_rest(with_contents)}\n}}}"
     end
 
     def trac