Lots of work related to generating more reference. Moving all of the individual references out of puppetdoc and into an external "reference" class, which itself can autoload, so it is now easy to add new types of references. Also adding a network reference, along with an unfinished provider reference.

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

15 files changed, 156 insertions, 2 deletions

diff --git a/lib/puppet/network/handler.rb b/lib/puppet/network/handler.rb
index 080997e98..33343e4fe 100644
--- a/lib/puppet/network/handler.rb
+++ b/lib/puppet/network/handler.rb
@@ -1,9 +1,12 @@
+require 'puppet/util/docs'
 require 'puppet/util/subclass_loader'
 
 module Puppet::Network
     # The base class for the different handlers.  The handlers are each responsible
     # for separate xmlrpc namespaces.
     class Handler
+        extend Puppet::Util::Docs
+
         # This is so that the handlers can subclass just 'Handler', rather
         # then having to specify the full class path.
         Handler = self
@@ -24,6 +27,20 @@ module Puppet::Network
             end
         end
 
+        # Set/Determine whether we're a client- or server-side handler.
+        def self.side(side = nil)
+            if side
+                side = side.intern if side.is_a?(String)
+                unless [:client, :server].include?(side)
+                    raise ArgumentError, "Invalid side registration '%s' for %s" % [side, self.name]
+                end
+                @side = side
+            else
+                @side ||= :server
+                return @side
+            end
+        end
+
         # Create an empty init method with the same signature.
         def initialize(hash = {})
         end
diff --git a/lib/puppet/network/handler/ca.rb b/lib/puppet/network/handler/ca.rb
index a52c1556e..875cfc926 100644
--- a/lib/puppet/network/handler/ca.rb
+++ b/lib/puppet/network/handler/ca.rb
@@ -10,6 +10,10 @@ class Puppet::Network::Handler
     class CA < Handler
         attr_reader :ca
 
+        desc "Provides an interface for signing CSRs.  Accepts a CSR and returns
+        the CA certificate and the signed certificate, or returns nil if
+        the cert is not signed."
+
         @interface = XMLRPC::Service::Interface.new("puppetca") { |iface|
             iface.add_method("array getcert(csr)")
         }
diff --git a/lib/puppet/network/handler/facts.rb b/lib/puppet/network/handler/facts.rb
index 46c94b91a..e0b93f942 100755
--- a/lib/puppet/network/handler/facts.rb
+++ b/lib/puppet/network/handler/facts.rb
@@ -4,6 +4,9 @@ require 'puppet/util/fact_store'
 class Puppet::Network::Handler
     # Receive logs from remote hosts.
     class Facts < Handler
+        desc "An interface for storing and retrieving client facts.  Currently only
+        used internally by Puppet."
+
         @interface = XMLRPC::Service::Interface.new("facts") { |iface|
             iface.add_method("void set(string, string)")
             iface.add_method("string get(string)")
diff --git a/lib/puppet/network/handler/filebucket.rb b/lib/puppet/network/handler/filebucket.rb
index 705a4eee9..bb6a0e6d3 100755
--- a/lib/puppet/network/handler/filebucket.rb
+++ b/lib/puppet/network/handler/filebucket.rb
@@ -8,6 +8,9 @@ class Puppet::Network::Handler # :nodoc:
     # to the client.  Alternatively, accept an md5 sum and return the
     # associated content.
     class FileBucket < Handler
+        desc "The interface to Puppet's FileBucket system.  Can be used to store
+        files in and retrieve files from a filebucket."
+
         @interface = XMLRPC::Service::Interface.new("puppetbucket") { |iface|
             iface.add_method("string addfile(string, string)")
             iface.add_method("string getfile(string)")
diff --git a/lib/puppet/network/handler/fileserver.rb b/lib/puppet/network/handler/fileserver.rb
index 0170eae7b..4331d27fd 100755
--- a/lib/puppet/network/handler/fileserver.rb
+++ b/lib/puppet/network/handler/fileserver.rb
@@ -7,6 +7,8 @@ require 'delegate'
 class Puppet::Network::Handler
     class FileServerError < Puppet::Error; end
     class FileServer < Handler
+        desc "The interface to Puppet's fileserving abilities."
+
         attr_accessor :local
 
         CHECKPARAMS = [:mode, :type, :owner, :group, :checksum]
diff --git a/lib/puppet/network/handler/master.rb b/lib/puppet/network/handler/master.rb
index 1082d3aaa..963b7841a 100644
--- a/lib/puppet/network/handler/master.rb
+++ b/lib/puppet/network/handler/master.rb
@@ -8,6 +8,9 @@ require 'yaml'
 class Puppet::Network::Handler
     class MasterError < Puppet::Error; end
     class Master < Handler
+        desc "Puppet's configuration interface.  Used for all interactions related to
+        generating client configurations."
+
         include Puppet::Util
 
         attr_accessor :ast, :local
diff --git a/lib/puppet/network/handler/report.rb b/lib/puppet/network/handler/report.rb
index e21acb810..ce5176a36 100755
--- a/lib/puppet/network/handler/report.rb
+++ b/lib/puppet/network/handler/report.rb
@@ -3,6 +3,8 @@ require 'puppet/util/instance_loader'
 # A simple server for triggering a new run on a Puppet client.
 class Puppet::Network::Handler
     class Report < Handler
+        desc "Accepts a Puppet transaction report and processes it."
+
         extend Puppet::Util::ClassGen
         extend Puppet::Util::InstanceLoader
 
diff --git a/lib/puppet/network/handler/resource.rb b/lib/puppet/network/handler/resource.rb
index 2937aa7be..349f73537 100755
--- a/lib/puppet/network/handler/resource.rb
+++ b/lib/puppet/network/handler/resource.rb
@@ -4,6 +4,16 @@ require 'puppet/network/handler'
 # Serve Puppet elements.  Useful for querying, copying, and, um, other stuff.
 class Puppet::Network::Handler
     class Resource < Handler
+        desc "An interface for interacting with client-based resources that can
+        be used for querying or managing remote machines without using Puppet's
+        central server tools.
+        
+        The ``describe`` and ``list`` methods return TransBuckets containing
+        TransObject instances (``describe`` returns a single TransBucket),
+        and the ``apply`` method accepts a TransBucket of TransObjects and
+        applies them locally.
+        "
+
         attr_accessor :local
 
         @interface = XMLRPC::Service::Interface.new("resource") { |iface|
@@ -12,6 +22,8 @@ class Puppet::Network::Handler
             iface.add_method("string list(string, array, string)")
         }
 
+        side :client
+
         # Apply a TransBucket as a transaction.
         def apply(bucket, format = "yaml", client = nil, clientip = nil)
             unless @local
diff --git a/lib/puppet/network/handler/runner.rb b/lib/puppet/network/handler/runner.rb
index 79084f847..c41e83608 100755
--- a/lib/puppet/network/handler/runner.rb
+++ b/lib/puppet/network/handler/runner.rb
@@ -2,10 +2,14 @@ class Puppet::Network::Handler
     class MissingMasterError < RuntimeError; end # Cannot find the master client
     # A simple server for triggering a new run on a Puppet client.
     class Runner < Handler
+        desc "An interface for triggering client configuration runs."
+
         @interface = XMLRPC::Service::Interface.new("puppetrunner") { |iface|
             iface.add_method("string run(string, string)")
         }
 
+        side :client
+
         # Run the client configuration right now, optionally specifying
         # tags and whether to ignore schedules
         def run(tags = nil, ignoreschedules = false, fg = true, client = nil, clientip = nil)
diff --git a/lib/puppet/network/handler/status.rb b/lib/puppet/network/handler/status.rb
index 774c49f6d..48668ca47 100644
--- a/lib/puppet/network/handler/status.rb
+++ b/lib/puppet/network/handler/status.rb
@@ -1,5 +1,9 @@
 class Puppet::Network::Handler
     class Status < Handler
+        desc "A simple interface for testing Puppet connectivity."
+
+        side :client
+
         @interface = XMLRPC::Service::Interface.new("status") { |iface|
             iface.add_method("int status()")
         }
diff --git a/lib/puppet/reference/network.rb b/lib/puppet/reference/network.rb
new file mode 100644
index 000000000..32a1fdd89
--- /dev/null
+++ b/lib/puppet/reference/network.rb
@@ -0,0 +1,33 @@
+network = Puppet::Util::Reference.newreference :network, :depth => 2, :doc => "Available network handlers and clients" do
+    ret = ""
+    Puppet::Network::Handler.subclasses.each do |name|
+        handler = Puppet::Network::Handler.handler(name)
+
+        next if ! handler.doc or handler.doc == ""
+
+        interface = handler.interface
+
+        ret += h(name, 2)
+
+        ret += scrub(handler.doc)
+        ret += "\n\n"
+        ret += option(:prefix, interface.prefix)
+        ret += option(:side, handler.side.to_s.capitalize)
+        ret += option(:methods, interface.methods.collect { |ary| ary[0] }.join(", ") )
+        ret += "\n\n"
+    end
+
+    ret
+end
+
+network.header = "
+This is a list of all Puppet network interfaces.  Each interface is
+implemented in the form of a client and a handler; the handler is loaded
+on the server, and the client knows how to call the handler's methods
+appropriately.
+
+Most handlers are meant to be started on the server, usually within
+``puppetmasterd``, and the clients are mostly started on the client,
+usually within ``puppetd``.
+
+"
diff --git a/lib/puppet/reference/providers.rb b/lib/puppet/reference/providers.rb
new file mode 100644
index 000000000..2d9d7f8cb
--- /dev/null
+++ b/lib/puppet/reference/providers.rb
@@ -0,0 +1,49 @@
+providers = Puppet::Util::Reference.newreference :providers, :doc => "Which providers are valid for this machine" do
+    types = []
+    Puppet::Type.loadall
+    Puppet::Type.eachtype do |klass|
+        next unless klass.providers.length > 0
+        types << klass
+    end
+    types.sort! { |a,b| a.name.to_s <=> b.name.to_s }
+
+    ret = ""
+    types.each do |type|
+        ret += h(type.name, 2)
+        features = type.features
+        unless features.empty?
+            ret += option("Available Features", features.collect { |f| f.to_s }.sort.join(", "))
+        end
+        ret += "\n" # add a trailing newline
+        type.providers.sort { |a,b| a.to_s <=> b.to_s }.each do |pname|
+            provider = type.provider(pname)
+            ret += h(provider.name, 3)
+
+            unless features.empty?
+                ret += option(:features, provider.features.collect { |a| a.to_s }.sort.join(", "))
+            end
+            if provider.suitable?
+                ret += option(:suitable?, "true")
+            else
+                ret += option(:suitable?, "false")
+            end
+            ret += "\n" # add a trailing newline
+        end
+        ret += "\n"
+    end
+
+    ret += "\n"
+
+    ret
+end
+providers.header = "
+Puppet resource types are usually backed by multiple implementations called ``providers``,
+which handle variance between platforms and tools.
+
+Different providers are suitable or unsuitable on different platforms based on things
+like the presence of a given tool.
+
+Here are all of the provider-backed types and their different providers.  Any unmentioned
+types do not use providers yet.
+
+"
diff --git a/lib/puppet/util/provider_features.rb b/lib/puppet/util/provider_features.rb
index 060026bb9..c8edd52ec 100644
--- a/lib/puppet/util/provider_features.rb
+++ b/lib/puppet/util/provider_features.rb
@@ -100,6 +100,12 @@ module Puppet::Util::ProviderFeatures
         str
     end
 
+    # Return a list of features.
+    def features
+        @features ||= {}
+        @features.keys
+    end
+
     # Generate a module that sets up the boolean methods to test for given
     # features.
     def feature_module
diff --git a/lib/puppet/util/reference.rb b/lib/puppet/util/reference.rb
index 3b1d7dd94..980baef4d 100644
--- a/lib/puppet/util/reference.rb
+++ b/lib/puppet/util/reference.rb
@@ -3,6 +3,7 @@ require 'puppet/util/instance_loader'
 # Manage Reference Documentation.
 class Puppet::Util::Reference
     include Puppet::Util
+    include Puppet::Util::Docs
 
     extend Puppet::Util::InstanceLoader
 
@@ -85,7 +86,7 @@ class Puppet::Util::Reference
     end
 
     def h(name, level)
-        return "%s\n%s\n" % [name, HEADER_LEVELS[level] * name.to_s.length]
+        return "%s\n%s\n\n" % [name, HEADER_LEVELS[level] * name.to_s.length]
     end
 
     def initialize(name, options = {}, &block)
@@ -108,6 +109,10 @@ class Puppet::Util::Reference
         return text.gsub(/(^|\A)/, tab).gsub(/^ +\.\./, "..")
     end
 
+    def option(name, value)
+        ":%s: %s\n" % [name.to_s.capitalize, value]
+    end
+
     def paramwrap(name, text, options = {})
         options[:level] ||= 5
         #str = "%s : " % name
diff --git a/lib/puppet/util/subclass_loader.rb b/lib/puppet/util/subclass_loader.rb
index 4f24d5544..00f011d03 100644
--- a/lib/puppet/util/subclass_loader.rb
+++ b/lib/puppet/util/subclass_loader.rb
@@ -1,6 +1,8 @@
 # A module for loading subclasses into an array and retrieving
 # them by name.  Also sets up a method for each class so
 # that you can just do Klass.subclass, rather than Klass.subclass(:subclass).
+#
+# This module is currently used by network handlers and clients.
 module Puppet::Util::SubclassLoader
     attr_accessor :loader, :classloader
 
@@ -48,7 +50,6 @@ module Puppet::Util::SubclassLoader
     # subclasses, thus the reason we're keeping track of the @@classloader.
     def inherited(sub)
         @subclasses ||= []
-        @subclasses << sub
         sub.classloader = self.classloader
         if self.classloader == self
             @subclasses << sub
@@ -78,6 +79,12 @@ module Puppet::Util::SubclassLoader
 
         return @name
     end
+
+    # Provide a list of all subclasses.
+    def subclasses
+        @loader.loadall
+        @subclasses.collect { |klass| klass.name }
+    end
 end
 
 # $Id$