Mostly done with the conversion to restructured text, but there are still some tweaks to perform on the typedocs output.

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

17 files changed, 105 insertions, 121 deletions

diff --git a/lib/puppet/metatype/metaparams.rb b/lib/puppet/metatype/metaparams.rb
index 2294f6170..e407ece24 100644
--- a/lib/puppet/metatype/metaparams.rb
+++ b/lib/puppet/metatype/metaparams.rb
@@ -25,7 +25,7 @@ class Puppet::Type
     newmetaparam(:schedule) do
         desc "On what schedule the object should be managed.  You must create a
             schedule object, and then reference the name of that object to use
-            that for your schedule:
+            that for your schedule::
 
                 schedule { daily:
                     period => daily,
@@ -150,7 +150,7 @@ class Puppet::Type
 
     newmetaparam(:alias) do
         desc "Creates an alias for the object.  Puppet uses this internally when you
-            provide a symbolic name:
+            provide a symbolic name::
             
                 file { sshdconfig:
                     path => $operatingsystem ? {
@@ -168,7 +168,7 @@ class Puppet::Type
             and the library sets that as an alias for the file so the dependency
             lookup for ``sshd`` works.  You can use this parameter yourself,
             but note that only the library can use these aliases; for instance,
-            the following code will not work:
+            the following code will not work::
 
                 file { \"/etc/ssh/sshd_config\":
                     owner => root,
@@ -183,9 +183,7 @@ class Puppet::Type
             There's no way here for the Puppet parser to know that these two stanzas
             should be affecting the same file.
 
-            See the [language tutorial][] for more information.
-
-            [language tutorial]: languagetutorial.html
+            See the `LanguageTutorial language tutorial`:trac: for more information.
             
             "
 
@@ -218,7 +216,7 @@ class Puppet::Type
             be useful to add your own tags to a given element.
 
             Tags are currently useful for things like applying a subset of a
-            host's configuration:
+            host's configuration::
                 
                 puppetd --test --tag mytag
 
@@ -317,7 +315,7 @@ class Puppet::Type
     newmetaparam(:require, :parent => RelationshipMetaparam, :attributes => {:direction => :in, :events => :NONE}) do
         desc "One or more objects that this object depends on.
             This is used purely for guaranteeing that changes to required objects
-            happen before the dependent object.  For instance:
+            happen before the dependent object.  For instance::
             
                 # Create the destination directory before you copy things down
                 file { \"/usr/local/scripts\":
@@ -353,7 +351,7 @@ class Puppet::Type
     newmetaparam(:subscribe, :parent => RelationshipMetaparam, :attributes => {:direction => :in, :events => :ALL_EVENTS, :callback => :refresh}) do
         desc "One or more objects that this object depends on.  Changes in the
             subscribed to objects result in the dependent objects being
-            refreshed (e.g., a service will get restarted).  For instance:
+            refreshed (e.g., a service will get restarted).  For instance::
             
                 class nagios {
                     file { \"/etc/nagios/nagios.conf\":
@@ -374,7 +372,7 @@ class Puppet::Type
     newmetaparam(:before, :parent => RelationshipMetaparam, :attributes => {:direction => :out, :events => :NONE}) do
         desc %{This parameter is the opposite of **require** -- it guarantees
             that the specified object is applied later than the specifying
-            object:
+            object::
 
                 file { "/var/nagios/configuration":
                     source  => "...",
@@ -393,7 +391,7 @@ class Puppet::Type
     
     newmetaparam(:notify, :parent => RelationshipMetaparam, :attributes => {:direction => :out, :events => :ALL_EVENTS, :callback => :refresh}) do
         desc %{This parameter is the opposite of **subscribe** -- it sends events
-            to the specified object:
+            to the specified object::
 
                 file { "/etc/sshd_config":
                     source => "....",
diff --git a/lib/puppet/type/cron.rb b/lib/puppet/type/cron.rb
index ca52d4ec9..ebf0fbe8a 100755
--- a/lib/puppet/type/cron.rb
+++ b/lib/puppet/type/cron.rb
@@ -17,7 +17,7 @@ Puppet::Type.newtype(:cron) do
         association is made and synced to disk, you can then manage the job
         normally (e.g., change the schedule of the job).
         
-        Example:
+        Example::
             
             cron { logrotate:
                 command => \"/usr/sbin/logrotate\",
@@ -293,8 +293,7 @@ Puppet::Type.newtype(:cron) do
             but will not associate them with a specific job.
             
             Settings should be specified exactly as they should appear in
-            the crontab, e.g., 'PATH=/bin:/usr/bin:/usr/sbin'.  Multiple
-            settings should be specified as an array."
+            the crontab, e.g., ``PATH=/bin:/usr/bin:/usr/sbin``."
 
         validate do |value|
             unless value =~ /^\s*(\w+)\s*=\s*(.+)\s*$/
@@ -324,10 +323,7 @@ Puppet::Type.newtype(:cron) do
             against specified jobs (and Puppet adds a comment to cron jobs it
             adds), but it is at least possible that converting from
             unmanaged jobs to managed jobs might require manual
-            intervention.
-            
-            The names can only have alphanumeric characters plus the '-'
-            character."
+            intervention."
 
         isnamevar
     end
@@ -339,7 +335,7 @@ Puppet::Type.newtype(:cron) do
             
             The user defaults to whomever Puppet is running as."
 
-        defaultto { ENV["USER"] }
+        defaultto { ENV["USER"] || "root" }
     end
 
     newproperty(:target) do
diff --git a/lib/puppet/type/exec.rb b/lib/puppet/type/exec.rb
index fd85d1202..ad33c755a 100755
--- a/lib/puppet/type/exec.rb
+++ b/lib/puppet/type/exec.rb
@@ -16,7 +16,7 @@ module Puppet
             share their commands with other instances as a dependency, since
             Puppet has no way of knowing which instance you mean.
 
-            For example:
+            For example::
 
                 # defined in the production class
                 exec { \"make\":
@@ -255,7 +255,7 @@ module Puppet
             desc "The command should only be run as a
                 refresh mechanism for when a dependent object is changed.  It only
                 makes sense to use this option when this command depends on some
-                other object; it is useful for triggering an action:
+                other object; it is useful for triggering an action::
                     
                     # Pull down the main aliases file
                     file { \"/etc/aliases\":
@@ -289,7 +289,7 @@ module Puppet
         newcheck(:creates) do 
             desc "A file that this command creates.  If this
                 parameter is provided, then the command will only be run
-                if the specified file does not exist.
+                if the specified file does not exist::
 
                     exec { \"tar xf /my/tar/file.tar\":
                         cwd => \"/var/tmp\",
@@ -322,7 +322,7 @@ module Puppet
 
         newcheck(:unless) do
             desc "If this parameter is set, then this ``exec`` will run unless
-                the command returns 0.  For example:
+                the command returns 0.  For example::
                     
                     exec { \"/bin/echo root >> /usr/lib/cron/cron.allow\":
                         path => \"/usr/bin:/usr/sbin:/bin\",
@@ -359,7 +359,7 @@ module Puppet
 
         newcheck(:onlyif) do
             desc "If this parameter is set, then this ``exec`` will only run if
-                the command returns 0.  For example:
+                the command returns 0.  For example::
                     
                     exec { \"logrotate\":
                         path => \"/usr/bin:/usr/sbin:/bin\",
diff --git a/lib/puppet/type/group.rb b/lib/puppet/type/group.rb
index 91c17580b..27d4b90d6 100755
--- a/lib/puppet/type/group.rb
+++ b/lib/puppet/type/group.rb
@@ -16,7 +16,7 @@ module Puppet
             membership must be managed on individual users.  This element type
             uses the prescribed native tools for creating groups and generally
             uses POSIX APIs for retrieving information about them.  It does
-            not directly modify /etc/group or anything.
+            not directly modify ``/etc/group`` or anything.
             
             For most platforms, the tools used are ``groupadd`` and its ilk;
             for Mac OS X, NetInfo is used.  This is currently unconfigurable,
diff --git a/lib/puppet/type/host.rb b/lib/puppet/type/host.rb
index ef56bc7c8..8a449da4b 100755
--- a/lib/puppet/type/host.rb
+++ b/lib/puppet/type/host.rb
@@ -102,7 +102,7 @@ module Puppet
         end
 
         @doc = "Installs and manages host entries.  For most systems, these
-            entries will just be in /etc/hosts, but some systems (notably OS X)
+            entries will just be in ``/etc/hosts``, but some systems (notably OS X)
             will have different solutions."
     end
 end
diff --git a/lib/puppet/type/package.rb b/lib/puppet/type/package.rb
index 14ce4a941..6bdbb02ad 100644
--- a/lib/puppet/type/package.rb
+++ b/lib/puppet/type/package.rb
@@ -43,8 +43,7 @@ module Puppet
                 to specify package versions, specify them here.  Similarly,
                 *purged* is only useful for packaging systems that support
                 the notion of managing configuration files separately from
-                'normal' system files.  At present, only the Debian-related
-                providers (dpkg, apt, and aptitude) support *purged*."
+                'normal' system files."
 
             attr_accessor :latest
 
@@ -200,7 +199,7 @@ module Puppet
             system uses internally, which is sometimes (especially on Solaris)
             a name that is basically useless to humans.  If you want to
             abstract package installation, then you can use aliases to provide
-            a common name to packages:
+            a common name to packages::
 
                 # In the 'openssl' class
                 $ssl = $operationgsystem ? {
diff --git a/lib/puppet/type/pfile.rb b/lib/puppet/type/pfile.rb
index c1b145519..080c5222f 100644
--- a/lib/puppet/type/pfile.rb
+++ b/lib/puppet/type/pfile.rb
@@ -46,7 +46,7 @@ module Puppet
                 
                 Puppet automatically creates a local filebucket named ``puppet`` and
                 defaults to backing up there.  To use a server-based filebucket,
-                you must specify one in your configuration:
+                you must specify one in your configuration::
                     
                     filebucket { main:
                         server => puppet
@@ -55,7 +55,7 @@ module Puppet
                 The ``puppetmasterd`` daemon creates a filebucket by default,
                 so you can usually back up to your main server with this
                 configuration.  Once you've described the bucket in your
-                configuration, you can use it in any file:
+                configuration, you can use it in any file::
 
                     file { \"/my/file\":
                         source => \"/path/in/nfs/or/something\",
diff --git a/lib/puppet/type/pfile/content.rb b/lib/puppet/type/pfile/content.rb
index 20ad5d6a2..e3e390179 100755
--- a/lib/puppet/type/pfile/content.rb
+++ b/lib/puppet/type/pfile/content.rb
@@ -3,7 +3,7 @@ module Puppet
         desc "Specify the contents of a file as a string.  Newlines, tabs, and
             spaces can be specified using the escaped syntax (e.g., \\n for a
             newline).  The primary purpose of this parameter is to provide a
-            kind of limited templating:
+            kind of limited templating::
 
                 define resolve(nameserver1, nameserver2, domain, search) {
                     $str = \"search $search
@@ -17,8 +17,8 @@ module Puppet
                     }
                 }
             
-                This attribute is especially useful when used with
-                [templating](/trac/puppet/wiki/PuppetTemplating)."
+            This attribute is especially useful when used with
+            `PuppetTemplating templating`:trac:."
 
         def change_to_s
             should = "{md5}" + Digest::MD5.hexdigest(self.should)
diff --git a/lib/puppet/type/pfile/ensure.rb b/lib/puppet/type/pfile/ensure.rb
index ea4154f80..658c3535e 100755
--- a/lib/puppet/type/pfile/ensure.rb
+++ b/lib/puppet/type/pfile/ensure.rb
@@ -9,14 +9,14 @@ module Puppet
             currently this will not recursively delete directories.
 
             Anything other than those values will be considered to be a symlink.
-            For instance, the following text creates a link:
+            For instance, the following text creates a link::
                 
                 # Useful on solaris
                 file { \"/etc/inetd.conf\":
                     ensure => \"/etc/inet/inetd.conf\"
                 }
             
-            You can make relative links:
+            You can make relative links::
                 
                 # Useful on solaris
                 file { \"/etc/inetd.conf\":
diff --git a/lib/puppet/type/pfile/source.rb b/lib/puppet/type/pfile/source.rb
index 3a22eb940..d3429c993 100755
--- a/lib/puppet/type/pfile/source.rb
+++ b/lib/puppet/type/pfile/source.rb
@@ -15,7 +15,7 @@ module Puppet
             This is one of the primary mechanisms for getting content into
             applications that Puppet does not directly support and is very
             useful for those configuration files that don't change much across
-            sytems.  For instance:
+            sytems.  For instance::
 
                 class sendmail {
                     file { \"/etc/mail/sendmail.cf\":
@@ -23,12 +23,12 @@ module Puppet
                     }
                 }
             
-            See the [fileserver docs][] for information on how to configure
+            See the `FileServingConfiguration`:trac: for information on how to configure
             and use file services within Puppet.
 
             If you specify multiple file sources for a file, then the first
             source that exists will be used.  This allows you to specify
-            what amount to search paths for files:
+            what amount to search paths for files::
 
                 file { \"/path/to/my/file\":
                     source => [
@@ -41,11 +41,7 @@ module Puppet
             This will use the first found file as the source.
             
             You cannot currently copy links using this mechanism; set ``links``
-            to ``follow`` if any remote sources are links.
-
-            [fileserver docs]: /trac/puppet/wiki/FileServingConfiguration
-
-            "
+            to ``follow`` if any remote sources are links."
 
         uncheckable
         
diff --git a/lib/puppet/type/pfilebucket.rb b/lib/puppet/type/pfilebucket.rb
index 162983e66..ec1803ff8 100755
--- a/lib/puppet/type/pfilebucket.rb
+++ b/lib/puppet/type/pfilebucket.rb
@@ -17,7 +17,7 @@ module Puppet
             undo transactions.
             
             You will normally want to define a single filebucket for your
-            whole network and then use that as the default backup location:
+            whole network and then use that as the default backup location::
             
                 # Define the bucket
                 filebucket { main: server => puppet }
@@ -26,8 +26,7 @@ module Puppet
                 File { backup => main }
 
             Puppetmaster servers create a filebucket by default, so this will
-            work in a default configuration.
-            "
+            work in a default configuration."
 
         newparam(:name) do
             desc "The name of the filebucket."
diff --git a/lib/puppet/type/schedule.rb b/lib/puppet/type/schedule.rb
index c68422849..3c3ce59a8 100755
--- a/lib/puppet/type/schedule.rb
+++ b/lib/puppet/type/schedule.rb
@@ -16,7 +16,7 @@ module Puppet
             Thus, it behooves you to use wider scheduling (e.g., over a couple of
             hours) combined with periods and repetitions.  For instance, if you
             wanted to restrict certain elements to only running once, between
-            the hours of two and 4 AM, then you would use this schedule:
+            the hours of two and 4 AM, then you would use this schedule::
                 
                 schedule { maint:
                     range => \"2 - 4\",
@@ -33,7 +33,7 @@ module Puppet
             Puppet automatically creates a schedule for each valid period with the
             same name as that period (e.g., hourly and daily).  Additionally,
             a schedule named *puppet* is created and used as the default,
-            with the following attributes:
+            with the following attributes::
 
                 schedule { puppet:
                     period => hourly,
@@ -45,7 +45,7 @@ module Puppet
 
         newparam(:name) do
             desc "The name of the schedule.  This name is used to retrieve the
-                schedule when assigning it to an object:
+                schedule when assigning it to an object::
                     
                     schedule { daily:
                         period => daily,
@@ -65,7 +65,7 @@ module Puppet
                 is always a range within a 24 hour period, and hours must be
                 specified in numbers between 0 and 23, inclusive.  Minutes and
                 seconds can be provided, using the normal colon as a separator.
-                For instance:
+                For instance::
 
                     schedule { maintenance:
                         range => \"1:30 - 4:30\"
@@ -189,7 +189,7 @@ module Puppet
         newparam(:periodmatch) do
             desc "Whether periods should be matched by number (e.g., the two times
                 are in the same hour) or by distance (e.g., the two times are
-                60 minutes apart). *number*/**distance**"
+                60 minutes apart)."
 
             newvalues(:number, :distance)
 
@@ -210,7 +210,7 @@ module Puppet
                 If the provided periods are not sufficient, you can provide a
                 value to the *repeat* attribute, which will cause Puppet to
                 schedule the affected elements evenly in the period the
-                specified number of times.  Take this schedule:
+                specified number of times.  Take this schedule::
 
                     schedule { veryoften:
                         period => hourly,
diff --git a/lib/puppet/type/service.rb b/lib/puppet/type/service.rb
index d568fa109..108df8968 100644
--- a/lib/puppet/type/service.rb
+++ b/lib/puppet/type/service.rb
@@ -32,7 +32,7 @@ module Puppet
             desc "Whether a service should be enabled to start at boot.
                 This property behaves quite differently depending on the platform;
                 wherever possible, it relies on local tools to enable or disable
-                a given service.  *true*/*false*/*runlevels*"
+                a given service."
 
             newvalue(:true, :event => :service_enabled) do
                 unless provider.respond_to?(:enable)
@@ -102,7 +102,7 @@ module Puppet
 
         # Handle whether the service should actually be running right now.
         newproperty(:ensure) do
-            desc "Whether a service should be running.  **true**/*false*"
+            desc "Whether a service should be running."
 
             newvalue(:stopped, :event => :service_stopped) do
                 provider.stop
@@ -184,7 +184,7 @@ module Puppet
         end
 
         newparam(:type) do
-            desc "Deprecated form of ``provder``."
+            desc "Deprecated form of ``provider``."
 
             munge do |value|
                 warning "'type' is deprecated; use 'provider' instead"
@@ -265,45 +265,6 @@ module Puppet
             newvalues(:true, :false)
         end
 
-        # Retrieve the default type for the current platform.
-        def self.disableddefaulttype
-            unless defined? @defsvctype
-                @defsvctype = nil
-                os = Facter["operatingsystem"].value
-                case os
-                when "Debian":
-                    @defsvctype = self.svctype(:debian)
-                when "Solaris":
-                    release = Facter["operatingsystemrelease"].value
-                    if release.sub(/5\./,'').to_i < 10
-                        @defsvctype = self.svctype(:init)
-                    else
-                        @defsvctype = self.svctype(:smf)
-                    end
-                when "CentOS", "RedHat", "Fedora":
-                    @defsvctype = self.svctype(:redhat)
-                else
-                    if Facter["kernel"] == "Linux"
-                        Puppet.notice "Using service type %s for %s" %
-                            ["init", Facter["operatingsystem"].value]
-                        @defsvctype = self.svctype(:init)
-                    end
-                end
-
-                unless @defsvctype
-                    Puppet.info "Defaulting to base service type"
-                    @defsvctype = self.svctype(:base)
-                end
-            end
-
-            unless defined? @notifieddefault
-                Puppet.debug "Default service type is %s" % @defsvctype.name
-                @notifieddefault = true
-            end
-
-            return @defsvctype.name
-        end
-
         # List all available services
         def self.list
             defprov = defaultprovider
diff --git a/lib/puppet/type/user.rb b/lib/puppet/type/user.rb
index 405a0b7a8..1bdfcf8df 100755
--- a/lib/puppet/type/user.rb
+++ b/lib/puppet/type/user.rb
@@ -10,11 +10,7 @@ module Puppet
             
             This element type uses the prescribed native tools for creating
             groups and generally uses POSIX APIs for retrieving information
-            about them.  It does not directly modify /etc/passwd or anything.
-            
-            For most platforms, the tools used are ``useradd`` and its ilk;
-            for Mac OS X, NetInfo is used.  This is currently unconfigurable,
-            but if you desperately need it to be so, please contact us."
+            about them.  It does not directly modify /etc/passwd or anything."
 
         feature :allows_duplicates,
             "The provider supports duplicate users with the same UID."
diff --git a/lib/puppet/type/zone.rb b/lib/puppet/type/zone.rb
index acae0d8b5..35d2a3d87 100644
--- a/lib/puppet/type/zone.rb
+++ b/lib/puppet/type/zone.rb
@@ -285,9 +285,8 @@ end
     # only used to boot the zone the very first time.
     newparam(:sysidcfg) do
         desc %{The text to go into the sysidcfg file when the zone is first
-            booted.  The best way is to use a template:
+            booted.  The best way is to use a template::
                 
-            <pre><code>
                 # $templatedir/sysidcfg
                 system_locale=en_US
                 timezone=GMT
@@ -303,9 +302,8 @@ end
                         protocol_ipv6=no
                         default_route=&lt;%= defaultroute %>}
                 nfs4_domain=dynamic
-            </code></pre>
 
-            And then call that:
+            And then call that::
 
                 zone { myzone:
                     ip => "bge0:192.168.0.23",
@@ -315,8 +313,7 @@ end
                 }
 
             The sysidcfg only matters on the first booting of the zone,
-            so Puppet only checks for it at that time.
-        }
+            so Puppet only checks for it at that time.}
     end
 
     newparam(:path) do
diff --git a/lib/puppet/util/docs.rb b/lib/puppet/util/docs.rb
index ebbce7317..38a6eeb26 100644
--- a/lib/puppet/util/docs.rb
+++ b/lib/puppet/util/docs.rb
@@ -27,6 +27,51 @@ module Puppet::Util::Docs
         end
     end
 
+    # Build a table
+    def doctable(headers, data)
+        str = "\n\n"
+
+        lengths = []
+        # Figure out the longest field for all columns
+        data.each do |name, values|
+            [name, values].flatten.each_with_index do |value, i|
+                lengths[i] ||= 0
+                lengths[i] = value.to_s.length if value.to_s.length > lengths[i]
+            end
+        end
+
+        # The headers could also be longest
+        headers.each_with_index do |value, i|
+            lengths[i] = value.to_s.length if value.to_s.length > lengths[i]
+        end
+
+        # Add the top header row
+        str += lengths.collect { |num| "=" * num }.join(" ") + "\n"
+
+        # And the header names
+        str += headers.zip(lengths).collect { |value, num| pad(value, num) }.join(" ") + "\n"
+
+        # And the second header row
+        str += lengths.collect { |num| "=" * num }.join(" ") + "\n"
+
+        # Now each data row
+        data.sort { |a, b| a[0].to_s <=> b[0].to_s }.each do |name, rows|
+            str += [name, rows].flatten.zip(lengths).collect do |value, length|
+                pad(value, length)
+            end.join(" ") + "\n"
+        end
+
+        # And the bottom line row
+        str += lengths.collect { |num| "=" * num }.join(" ") + "\n"
+
+        str + "\n"
+    end
+
+    # Pad a field with spaces
+    def pad(value, length)
+        value.to_s + (" " * (length - value.to_s.length))
+    end
+
     # Handle the inline indentation in the docs.
     def scrub(text)
         # Stupid markdown
diff --git a/lib/puppet/util/provider_features.rb b/lib/puppet/util/provider_features.rb
index 773f0ec98..b6e54b5bd 100644
--- a/lib/puppet/util/provider_features.rb
+++ b/lib/puppet/util/provider_features.rb
@@ -1,10 +1,10 @@
 # Provides feature definitions.
 module Puppet::Util::ProviderFeatures
-
     # The class that models the features and handles checking whether the features
     # are present.
     class ProviderFeature
         require 'puppet/util/methodhelper'
+        require 'puppet/util/docs'
         require 'puppet/util'
         include Puppet::Util
         include Puppet::Util::MethodHelper
@@ -76,27 +76,24 @@ module Puppet::Util::ProviderFeatures
         names = @features.keys.sort { |a,b| a.to_s <=> b.to_s }
         names.each do |name|
             doc = @features[name].docs.gsub(/\n\s+/, " ")
-            str += " - **%s**: %s\n" % [name, doc]
+            str += "- **%s**: %s\n" % [name, doc]
         end
+
         if providers.length > 0
-            str += "<table><tr><th></th>\n"
-            names.each do |name|
-                str += "<th>%s</th>" % name
-            end
-            str += "</tr>\n"
+            headers = ["Provider", names].flatten
+            data = {}
             providers.each do |provname|
+                data[provname] = []
                 prov = provider(provname)
-                str += "<tr><td>%s</td>" % provname
-                names.each do |feature|
-                    have = ""
-                    if prov.feature?(feature)
-                        have = "<strong>X</strong>"
+                names.each do |name|
+                    if prov.feature?(name)
+                        data[provname] << "**X**"
+                    else
+                        data[provname] << ""
                     end
-                    str += "<td>%s</td>" % have
                 end
-                str += "</tr>\n"
             end
-            str += "</table>\n"
+            str += doctable(headers, data)
         end
         str
     end