Adding doc generation for exe arguments

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

1 files changed, 160 insertions, 108 deletions

diff --git a/bin/puppetdoc b/bin/puppetdoc
index 526f392b7..b8e6619cd 100755
--- a/bin/puppetdoc
+++ b/bin/puppetdoc
@@ -8,19 +8,26 @@
 #
 # = Usage
 #
-#   puppetdoc [-h|--help]
+#   puppetdoc [-h|--help] [-a|--arguments] [-t|--types]
 #
 # = Description
 #
 # This command generates a restructured-text document describing all installed
-# Puppet types.  It is largely meant for internal use and is used to generate
-# the reference document available on the Reductive Labs web site.
+# Puppet types or all allowable arguments to puppet executables.  It is largely
+# meant for internal use and is used to generate the reference document
+# available on the Reductive Labs web site.
 #
 # = Options
 #
+# arguments::
+#   Print the documentation for arguments.
+#
 # help::
 #   Print this help message
 #
+# types::
+#   Print the argumenst for Puppet types.  This is the default.
+#
 # = Example
 #
 #   $ puppetdoc > /tmp/reference.rst
@@ -46,6 +53,8 @@ rescue LoadError
 end
 
 result = GetoptLong.new(
+	[ "--arguments",	"-a",			GetoptLong::NO_ARGUMENT ],
+	[ "--types",	"-t",			GetoptLong::NO_ARGUMENT ],
 	[ "--help",		"-h",			GetoptLong::NO_ARGUMENT ]
 )
 
@@ -53,9 +62,15 @@ debug = false
 
 $tab = "    "
 
+mode = :types
+
 begin
     result.each { |opt,arg|
         case opt
+            when "--arguments"
+                mode = :arguments
+            when "--types"
+                mode = :types
             when "--help"
                 if $haveusage
                     RDoc::usage && exit
@@ -96,22 +111,56 @@ def indent(text, tab)
     return text.gsub(/(^|\A)/, tab).gsub(/^ +\.\./, "..")
 end
 
-#def tab(num)
-#    return $tab * num
-#end
+# Print the docs for arguments
+def self.arguments
+    puts %{
+===========================
+Puppet Executable Reference
+===========================
+
+Every Puppet executable (with the exception of ``puppetdoc``) accepts all of
+these arguments, but not all of the arguments make sense for every executable.
+Each argument has a section listed with it in parentheses; often, that section
+will map to an executable (e.g., ``puppetd``), in which case it probably only
+makes sense for that one executable.  If ``puppet`` is listed as the section,
+it is most likely an option that is valid for everyone.
+
+This will not always be the case.  I have tried to be as thorough as possible
+in the descriptions of the arguments, so it should be obvious whether an
+argument is approprite or not.
+
+}
+
+    docs = {}
+    Puppet.config.each do |name, object|
+        docs[name] = object
+    end
+
+    docs.sort { |a, b|
+        a[0].to_s <=> b[0].to_s
+    }.each do |name, object|
+        puts "* **#{name.to_s}** (*#{object.section.to_s}*)"
+        puts ""
+        puts "  " + object.desc.gsub(/\n/, " ")
+        puts ""
+    end
+
+end
 
-puts %{
+# Print the docs for types
+def self.types
+    puts %{
 ==============
 Type Reference
 ==============
 
-}
+    }
 
-types = {}
-Puppet::Type.eachtype { |type|
-    types[type.name] = type
-}
-puts %{
+    types = {}
+    Puppet::Type.eachtype { |type|
+        types[type.name] = type
+    }
+    puts %{
 ---------------
 Meta-Parameters
 ---------------
@@ -121,26 +170,26 @@ Puppet framework itself rather than being part of the implementation of any
 given instance.  Thus, any defined metaparameter can be used with any instance
 in your manifest, including defined components.
 
-}
-begin
-    params = []
-    Puppet::Type.eachmetaparam { |param|
-        params << param
-    }
-
-    params.sort { |a,b|
-        a.to_s <=> b.to_s
-    }.each { |param|
-        puts "- **" + param.to_s + "**"
-        #puts tab(1) + Puppet::Type.metaparamdoc(param).scrub.indent($tab)gsub(/\n\s*/,' ')
-        puts indent(scrub(Puppet::Type.metaparamdoc(param)), $tab)
     }
-rescue => detail
-    puts "incorrect metaparams: %s" % detail
-    exit(1)
-end
+    begin
+        params = []
+        Puppet::Type.eachmetaparam { |param|
+            params << param
+        }
+
+        params.sort { |a,b|
+            a.to_s <=> b.to_s
+        }.each { |param|
+            puts "- **" + param.to_s + "**"
+            #puts tab(1) + Puppet::Type.metaparamdoc(param).scrub.indent($tab)gsub(/\n\s*/,' ')
+            puts indent(scrub(Puppet::Type.metaparamdoc(param)), $tab)
+        }
+    rescue => detail
+        puts "incorrect metaparams: %s" % detail
+        exit(1)
+    end
 
-puts %{
+    puts %{
 -----
 Types
 -----
@@ -167,99 +216,102 @@ Types
   how the instance behaves (e.g., adding a search path for ``exec`` instances
   or determining recursion on ``file`` instances).
 
-}
+    }
 
-types.sort { |a,b|
-    a.to_s <=> b.to_s
-}.each { |name,type|
-    next if name == :puppet
-    next if name == :component
+    types.sort { |a,b|
+        a.to_s <=> b.to_s
+    }.each { |name,type|
+        next if name == :puppet
+        next if name == :component
 
-    puts "
+        puts "
 
 ----------------
 
 "
 
-    puts "
+        puts "
 %s
 %s" % [name, "=" * (name.to_s.length + 4)]
-    #String.new('n%s\n') % name.to_s
-    #puts "**" + type.doc.gsub(/\n\s*/, ' ') + "**\n\n"
-    puts scrub(type.doc) + "\n\n"
-
-    #puts tab(1) + "* namevar: %s" % type.namevar
-    docs = {}
-    #puts "%s States\n'''''''''''''''''''''''''''''''" % name.to_s.capitalize
-    type.validstates.sort { |a,b|
-        a.to_s <=> b.to_s
-    }.reject { |sname|
-        state = type.statebyname(sname)
-        state.nodoc
-    }.each { |sname|
-        state = type.statebyname(sname)
-
-        unless state
-            raise "Could not retrieve state %s on type %s" % [sname, type.name]
-        end
-
-        doc = nil
-        str = nil
-        unless doc = state.doc
-            $stderr.puts "No docs for %s[%s]" % [type, sname]
-            next
-        end
-        doc = doc.dup
-        str = doc
-        #puts "A---" + str + "---"
-        str = scrub(str)
-        #puts "B---" + str + "---"
-        #str = indent(str, $tab)
-        #puts "C---" + str + "---"
-        #str = indent($tab, scrub(doc))
-
-        # If the state has values, then add them: 
-
-        #if values = state.values
-        #    unless values.empty?
-        #        extra = "Acceptable values are %s." % values.join(", ")
-        #        str += "\n\n#{extra}"
-        #    end
-        #end
-
-        str = indent(str, $tab)
-        #puts "---" + str + "---"
-        docs[sname]  = str
-        #puts "- **%s**" % sname
-        #puts tab(1) + state.doc.gsub(/\n\s*/,' ')
-    }
-
-    puts "\n%s Parameters\n''''''''''''''''''''''''''''''" % name.to_s.capitalize
-    type.parameters.sort { |a,b|
-        a.to_s <=> b.to_s
-    }.each { |name,param|
-        docs[name] = indent(scrub(type.paramdoc(name)), $tab)
+        #String.new('n%s\n') % name.to_s
+        #puts "**" + type.doc.gsub(/\n\s*/, ' ') + "**\n\n"
+        puts scrub(type.doc) + "\n\n"
+
+        #puts tab(1) + "* namevar: %s" % type.namevar
+        docs = {}
+        #puts "%s States\n'''''''''''''''''''''''''''''''" % name.to_s.capitalize
+        type.validstates.sort { |a,b|
+            a.to_s <=> b.to_s
+        }.reject { |sname|
+            state = type.statebyname(sname)
+            state.nodoc
+        }.each { |sname|
+            state = type.statebyname(sname)
+
+            unless state
+                raise "Could not retrieve state %s on type %s" % [sname, type.name]
+            end
+
+            doc = nil
+            str = nil
+            unless doc = state.doc
+                $stderr.puts "No docs for %s[%s]" % [type, sname]
+                next
+            end
+            doc = doc.dup
+            str = doc
+            #puts "A---" + str + "---"
+            str = scrub(str)
+            #puts "B---" + str + "---"
+            #str = indent(str, $tab)
+            #puts "C---" + str + "---"
+            #str = indent($tab, scrub(doc))
+
+            # If the state has values, then add them: 
+
+            #if values = state.values
+            #    unless values.empty?
+            #        extra = "Acceptable values are %s." % values.join(", ")
+            #        str += "\n\n#{extra}"
+            #    end
+            #end
+
+            str = indent(str, $tab)
+            #puts "---" + str + "---"
+            docs[sname]  = str
+            #puts "- **%s**" % sname
+            #puts tab(1) + state.doc.gsub(/\n\s*/,' ')
+        }
+
+        puts "\n%s Parameters\n''''''''''''''''''''''''''''''" % name.to_s.capitalize
+        type.parameters.sort { |a,b|
+            a.to_s <=> b.to_s
+        }.each { |name,param|
+            docs[name] = indent(scrub(type.paramdoc(name)), $tab)
+        }
+
+        docs.sort { |a, b|
+            a[0].to_s <=> b[0].to_s
+        }.each { |name, doc|
+            print "- **%s**" % name
+            if type.namevar == name and name != :name
+                puts " (*namevar*)"
+            else
+                puts ""
+            end
+            puts doc
+        }
+        puts "\n"
     }
+end
 
-    docs.sort { |a, b|
-        a[0].to_s <=> b[0].to_s
-    }.each { |name, doc|
-        print "- **%s**" % name
-        if type.namevar == name and name != :name
-            puts " (*namevar*)"
-        else
-            puts ""
-        end
-        puts doc
-    }
-    puts "\n"
-}
+send(mode)
 
 puts "
 
 ----------------
 
 "
-
 puts "\n*This page autogenerated on %s*" % Time.now
+
 # $Id$