diff --git a/lib/puppet/application/doc.rb b/lib/puppet/application/doc.rb index 66aa6c8a1..6ebb47563 100644 --- a/lib/puppet/application/doc.rb +++ b/lib/puppet/application/doc.rb @@ -1,215 +1,207 @@ require 'puppet/application' class Puppet::Application::Doc < Puppet::Application should_not_parse_config run_mode :master attr_accessor :unknown_args, :manifest def preinit {:references => [], :mode => :text, :format => :to_rest }.each do |name,value| options[name] = value end @unknown_args = [] @manifest = false end option("--all","-a") option("--outputdir OUTPUTDIR","-o") option("--verbose","-v") option("--debug","-d") option("--charset CHARSET") option("--format FORMAT", "-f") do |arg| method = "to_#{arg}" require 'puppet/util/reference' if Puppet::Util::Reference.method_defined?(method) options[:format] = method else raise "Invalid output format #{arg}" end end option("--mode MODE", "-m") do |arg| require 'puppet/util/reference' if Puppet::Util::Reference.modes.include?(arg) or arg.intern==:rdoc options[:mode] = arg.intern else raise "Invalid output mode #{arg}" end end option("--list", "-l") do |arg| require 'puppet/util/reference' puts Puppet::Util::Reference.references.collect { |r| Puppet::Util::Reference.reference(r).doc }.join("\n") exit(0) end option("--reference REFERENCE", "-r") do |arg| options[:references] << arg.intern end def handle_unknown( opt, arg ) @unknown_args << {:opt => opt, :arg => arg } true end def run_command - return[:rdoc, :trac, :markdown].include?(options[:mode]) ? send(options[:mode]) : other + return[:rdoc, :markdown].include?(options[:mode]) ? send(options[:mode]) : other end def rdoc exit_code = 0 files = [] unless @manifest env = Puppet::Node::Environment.new files += env.modulepath files << File.dirname(env[:manifest]) end files += command_line.args Puppet.info "scanning: #{files.inspect}" Puppet.settings.setdefaults( "puppetdoc", - + "document_all" => [false, "Document all resources"] ) Puppet.settings[:document_all] = options[:all] || false begin require 'puppet/util/rdoc' if @manifest Puppet::Util::RDoc.manifestdoc(files) else options[:outputdir] = "doc" unless options[:outputdir] Puppet::Util::RDoc.rdoc(options[:outputdir], files, options[:charset]) end rescue => detail puts detail.backtrace if Puppet[:trace] $stderr.puts "Could not generate documentation: #{detail}" exit_code = 1 end exit exit_code end - def trac - require 'puppet/util/reference' - options[:references].each do |name| - section = Puppet::Util::Reference.reference(name) or raise "Could not find section #{name}" - section.trac unless options[:mode] == :pdf - end - end - def markdown text = "" with_contents = false exit_code = 0 require 'puppet/util/reference' options[:references].sort { |a,b| a.to_s <=> b.to_s }.each do |name| raise "Could not find reference #{name}" unless section = Puppet::Util::Reference.reference(name) begin # Add the per-section text, but with no ToC text += section.send(options[:format], with_contents) text += Puppet::Util::Reference.footer text.gsub!(/`\w+\s+([^`]+)`:trac:/) { |m| $1 } Puppet::Util::Reference.markdown(name, text) text = "" rescue => detail puts detail.backtrace $stderr.puts "Could not generate reference #{name}: #{detail}" exit_code = 1 next end end exit exit_code end def other text = "" with_contents = options[:references].length <= 1 exit_code = 0 require 'puppet/util/reference' options[:references].sort { |a,b| a.to_s <=> b.to_s }.each do |name| raise "Could not find reference #{name}" unless section = Puppet::Util::Reference.reference(name) begin # Add the per-section text, but with no ToC text += section.send(options[:format], with_contents) rescue => detail puts detail.backtrace $stderr.puts "Could not generate reference #{name}: #{detail}" exit_code = 1 next end end text += Puppet::Util::Reference.footer unless with_contents # We've only got one reference # Replace the trac links, since they're invalid everywhere else text.gsub!(/`\w+\s+([^`]+)`:trac:/) { |m| $1 } if options[:mode] == :pdf Puppet::Util::Reference.pdf(text) else puts text end exit exit_code end def setup # sole manifest documentation if command_line.args.size > 0 options[:mode] = :rdoc @manifest = true end if options[:mode] == :rdoc setup_rdoc else setup_reference end end def setup_reference if options[:all] # Don't add dynamic references to the "all" list. require 'puppet/util/reference' options[:references] = Puppet::Util::Reference.references.reject do |ref| Puppet::Util::Reference.reference(ref).dynamic? end end options[:references] << :type if options[:references].empty? end def setup_rdoc(dummy_argument=:work_arround_for_ruby_GC_bug) # consume the unknown options # and feed them as settings if @unknown_args.size > 0 @unknown_args.each do |option| # force absolute path for modulepath when passed on commandline if option[:opt]=="--modulepath" or option[:opt] == "--manifestdir" option[:arg] = option[:arg].split(':').collect { |p| File.expand_path(p) }.join(':') end Puppet.settings.handlearg(option[:opt], option[:arg]) end end # Now parse the config Puppet.parse_config # Handle the logging settings. if options[:debug] or options[:verbose] if options[:debug] Puppet::Util::Log.level = :debug else Puppet::Util::Log.level = :info end Puppet::Util::Log.newdestination(:console) end end end diff --git a/lib/puppet/util/reference.rb b/lib/puppet/util/reference.rb index 62bab643e..3fdd37f68 100644 --- a/lib/puppet/util/reference.rb +++ b/lib/puppet/util/reference.rb @@ -1,207 +1,184 @@ require 'puppet/util/instance_loader' require 'fileutils' # Manage Reference Documentation. class Puppet::Util::Reference include Puppet::Util include Puppet::Util::Docs extend Puppet::Util::InstanceLoader instance_load(:reference, 'puppet/reference') def self.footer "\n\n----------------\n\n*This page autogenerated on #{Time.now}*\n" end def self.modes - %w{pdf trac text markdown} + %w{pdf text markdown} end def self.newreference(name, options = {}, &block) ref = self.new(name, options, &block) instance_hash(:reference)[symbolize(name)] = ref ref end def self.page(*sections) depth = 4 # Use the minimum depth sections.each do |name| section = reference(name) or raise "Could not find section #{name}" depth = section.depth if section.depth < depth end text = ".. contents:: :depth: 2\n\n" end def self.pdf(text) puts "creating pdf" Puppet::Util.secure_open("/tmp/puppetdoc.txt", "w") do |f| f.puts text end rst2latex = %x{which rst2latex} if $CHILD_STATUS != 0 or rst2latex =~ /no / rst2latex = %x{which rst2latex.py} end if $CHILD_STATUS != 0 or rst2latex =~ /no / raise "Could not find rst2latex" end rst2latex.chomp! cmd = %{#{rst2latex} /tmp/puppetdoc.txt > /tmp/puppetdoc.tex} Puppet::Util.secure_open("/tmp/puppetdoc.tex","w") do |f| # If we get here without an error, /tmp/puppetdoc.tex isn't a tricky cracker's symlink end output = %x{#{cmd}} unless $CHILD_STATUS == 0 $stderr.puts "rst2latex failed" $stderr.puts output exit(1) end $stderr.puts output # Now convert to pdf Dir.chdir("/tmp") do %x{texi2pdf puppetdoc.tex >/dev/null 2>/dev/null} end end def self.markdown(name, text) puts "Creating markdown for #{name} reference." dir = "/tmp/#{Puppet::PUPPETVERSION}" FileUtils.mkdir(dir) unless File.directory?(dir) Puppet::Util.secure_open(dir + "/#{name}.rst", "w") do |f| f.puts text end pandoc = %x{which pandoc} if $CHILD_STATUS != 0 or pandoc =~ /no / pandoc = %x{which pandoc} end if $CHILD_STATUS != 0 or pandoc =~ /no / raise "Could not find pandoc" end pandoc.chomp! cmd = %{#{pandoc} -s -r rst -w markdown #{dir}/#{name}.rst -o #{dir}/#{name}.mdwn} output = %x{#{cmd}} unless $CHILD_STATUS == 0 $stderr.puts "Pandoc failed to create #{name} reference." $stderr.puts output exit(1) end File.unlink(dir + "/#{name}.rst") end def self.references instance_loader(:reference).loadall loaded_instances(:reference).sort { |a,b| a.to_s <=> b.to_s } end HEADER_LEVELS = [nil, "=", "-", "+", "'", "~"] attr_accessor :page, :depth, :header, :title, :dynamic attr_writer :doc def doc if defined?(@doc) return "#{@name} - #{@doc}" else return @title end end def dynamic? self.dynamic end def h(name, level) "#{name}\n#{HEADER_LEVELS[level] * name.to_s.length}\n\n" end def initialize(name, options = {}, &block) @name = name options.each do |option, value| send(option.to_s + "=", value) end meta_def(:generate, &block) # Now handle the defaults @title ||= "#{@name.to_s.capitalize} Reference" @page ||= @title.gsub(/\s+/, '') @depth ||= 2 @header ||= "" end # Indent every line in the chunk except those which begin with '..'. def indent(text, tab) text.gsub(/(^|\A)/, tab).gsub(/^ +\.\./, "..") end def option(name, value) ":#{name.to_s.capitalize}: #{value}\n" end def paramwrap(name, text, options = {}) options[:level] ||= 5 #str = "#{name} : " str = h(name, options[:level]) str += "- **namevar**\n\n" if options[:namevar] str += text #str += text.gsub(/\n/, "\n ") str += "\n\n" end # Remove all trac links. def strip_trac(text) text.gsub(/`\w+\s+([^`]+)`:trac:/) { |m| $1 } end def text puts output end def to_rest(withcontents = true) # First the header text = h(@title, 1) text += "\n\n**This page is autogenerated; any changes will get overwritten** *(last generated on #{Time.now.to_s})*\n\n" text += ".. contents:: :depth: #{@depth}\n\n" if withcontents text += @header text += generate text += self.class.footer if withcontents text end 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 - Puppet::Util.secure_open("/tmp/puppetdoc.txt", "w") do |f| - f.puts self.to_trac - end - - puts "Writing #{@name} reference to trac as #{@page}" - cmd = %{sudo trac-admin /opt/rl/trac/puppet wiki import %s /tmp/puppetdoc.txt} % self.page - output = %x{#{cmd}} - unless $CHILD_STATUS == 0 - $stderr.puts "trac-admin failed" - $stderr.puts output - exit(1) - end - unless output =~ /^\s+/ - $stderr.puts output - end - end end - diff --git a/tasks/rake/tracdocs.rake b/tasks/rake/tracdocs.rake deleted file mode 100644 index d26d8fc17..000000000 --- a/tasks/rake/tracdocs.rake +++ /dev/null @@ -1,8 +0,0 @@ -task :tracdocs do - require 'puppet' - require 'puppet/util/reference' - Puppet::Util::Reference.references.each do |ref| - sh "puppetdoc -m trac -r #{ref.to_s}" - end -end -