The initial documentation for 4.2.X

This is the initial push of the 4.2.X documentation. Additional build
documentation will be coming soon.

Rakefile

@@ -0,0 +1,59 @@
+#!/usr/bin/rake -T
+
+require 'simp/rake'
+
+class DocPkg < Simp::Rake::Pkg
+  def define_clean
+    task :clean do
+      find_erb_files.each do |erb|
+        short_name = "#{File.dirname(erb)}/#{File.basename(erb,'.erb')}"
+        if File.exist?(short_name) then
+          rm(short_name)
+        end
+      end
+
+      Rake::Task['rdoc:clean'].invoke
+    end
+  end
+
+  def define_pkg_tar
+    # First, we need to assemble the documentation.
+    # This doesn't work properly under Ruby >= 1.9 and leaves cruft in the directories
+    # We can try again when 'puppet strings' hits the ground
+    if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('1.9')
+      Rake::Task['rdoc:build'].invoke
+    end
+
+    Rake::Task['publican:build'].invoke(@spec_file)
+
+    super
+  end
+
+  def find_erb_files(dir=@base_dir)
+    to_ret = []
+    Find.find(dir) do |erb|
+      if erb =~ /\.erb$/ then
+        to_ret << erb
+      end
+    end
+
+    to_ret
+  end
+end
+
+DocPkg.new( File.dirname( __FILE__ ) ) do |t|
+  # Not sure this is right
+  t.clean_list << "#{t.base_dir}/build_docs"
+  t.clean_list << "#{t.base_dir}/html/user_guide/*"
+  t.clean_list << "#{t.base_dir}/pdf"
+
+  t.exclude_list << 'dist'
+  t.exclude_list << 'build_docs'
+
+  # Need to ignore any generated files from ERB's.
+  #t.ignore_changes_list += find_erb_files.map{|x| x = "#{File.dirname(x)}/#{File.basename(x,'.erb')}".sub(/^\.\//,'')}
+
+  Dir.glob('build/rake_helpers/*.rake').each do |helper|
+    load helper
+  end
+end

build/package_metadata.yaml

@@ -0,0 +1,5 @@
+---
+# This RPM is required by the main SIMP RPM
+optional: false
+valid_versions:
+ - '4\.1.*'

build/rake_helpers/publican.rake

@@ -0,0 +1,194 @@
+#!/usr/bin/rake -T
+namespace :publican do
+
+  verbose(false)
+
+  require 'cgi'
+  require 'erb'
+  require 'find'
+  require 'rexml/document'
+  require 'simp/rpm'
+  include REXML
+
+  # The following two directories are for code that depends on the
+  # rest of the build tree being in place. If these do not exist, a
+  # warning will be issued.
+  BUILD_DIR = File.expand_path(File.dirname(__FILE__) + '/../../../../build')
+  MODULE_DIR = File.expand_path(File.dirname(__FILE__) + '/../../../puppet/modules')
+
+  PUBLICAN_DIR = 'publican/'
+  DOC_HEAD_DIR = 'build_docs/'
+  DOC_BUILD_DIR = DOC_HEAD_DIR + "en-US/"
+  DOC_TMP_HTML_DIR = DOC_BUILD_DIR + "html/"
+  DOC_TMP_HTML_SINGLE_DIR = DOC_BUILD_DIR + "html-single/"
+  DOC_FINAL_HTML_DIR = 'html/users_guide/'
+  DOC_FINAL_HTML_SINGLE_DIR = 'html/users_guide/single/'
+
+  desc <<-EOM
+    Builds the SIMP user documentation for packaging
+
+    This task does *not* build the PDF, the RPM does that.
+  EOM
+  task :build,[:spec_file, :product_number, :os_version, :cleanup, :verbose] do |t,args|
+    args.with_defaults(:verbose => false)
+    args.with_defaults(:cleanup => true)
+    args.with_defaults(:os_version => 'STUB_OS_VERSION')
+
+    fail "A spec file must be specified" if not args.spec_file
+
+    verbose = args.verbose
+
+    doc_product_number = Simp::RPM.get_info(args.spec_file)
+
+    # Remove any previous results from running publican
+    verbose and puts "Removing old publican build_docs directory to avoid conflict"
+    if File.directory?("#{DOC_HEAD_DIR}") then FileUtils.rm_rf("#{DOC_HEAD_DIR}") end
+
+    verbose and puts "Removing any previous HTML user guide documentation"
+    if File.directory?("#{DOC_FINAL_HTML_DIR}") then FileUtils.rm_rf("#{DOC_FINAL_HTML_DIR}") end
+
+    verbose and puts "Removing any previous HTML-single user guide documentation"
+    if File.directory?("#{DOC_FINAL_HTML_SINGLE_DIR}") then FileUtils.rm_rf("#{DOC_FINAL_HTML_SINGLE_DIR}") end
+
+    # Create directories for the finished results
+    verbose and puts "Recreating the html and pdf directories for the final output"
+    FileUtils.mkdir("#{DOC_FINAL_HTML_DIR}")
+    FileUtils.mkdir("#{DOC_FINAL_HTML_SINGLE_DIR}")
+
+    # Update the publican.cfg.
+    fh = File.open("#{PUBLICAN_DIR}/publican.cfg",'w')
+    fh.puts(ERB.new(File.read("#{PUBLICAN_DIR}/publican.cfg.erb"),nil,'-').result(binding))
+    fh.close
+
+    # Update the SIMP_Documentation.ent with the latest version number and
+    # the RHEL release.
+    fh = File.open("#{PUBLICAN_DIR}/en-US/SIMP_Documentation.ent",'w')
+    fh.puts(ERB.new(File.read("#{PUBLICAN_DIR}/en-US/SIMP_Documentation.ent.erb"),nil,'-').result(binding))
+    fh.close
+
+    # Update the changelog from the template
+    !File.readable?("Changelog.txt") and raise Error("Error: Could not find Changelog.txt!")
+
+    # Have to split this into multiple files since Publican dies at 8192 bytes!
+    changelog_txt = CGI.escapeHTML(File.read("Changelog.txt"))
+
+    fh = File.open("#{PUBLICAN_DIR}/en-US/common/Changelog.xml",'w')
+    fh.puts(ERB.new(File.read("#{PUBLICAN_DIR}/en-US/common/Changelog.xml.erb"),nil,'-').result(binding))
+    fh.close
+
+    build_rpm_source_appendix
+    build_module_installed_appendix(doc_product_number)
+  end # End of doc_build task
+
+  desc "Generate the publican PDF"
+  task :gendoc,[:version,:format,:lang] do |t,args|
+    args.with_defaults(:format => 'pdf')
+    args.with_defaults(:lang => 'en-US')
+
+    Rake::Task['publican:build'].invoke(args.version)
+
+    Dir.chdir(PUBLICAN_DIR) do
+      sh %{publican build --formats=#{args.format} --langs=#{args.lang}}
+    end
+
+    FileUtils.mkdir('pdf') unless File.directory?('pdf')
+    FileUtils.mv(Dir.glob("build_docs/#{args.lang}/pdf/*.pdf"),'pdf')
+  end
+
+  def build_module_installed_appendix(doc_product_number)
+    stubbin_time = false
+    if not File.directory?(MODULE_DIR) then
+      $stderr.puts("Warning: Could not find the module directory '#{MODULE_DIR}'. Skipping installed module appendix")
+      stubbin_time = true
+    else
+      # And now, another Appendix that holds the list of pupmod RPMs
+      # installed, and not installed, by default.
+      modules = {}
+
+      module_default = YAML.load(File.read('../build/package_metadata_defaults.yaml'))['optional']
+
+      Dir.chdir(MODULE_DIR) do
+
+        Dir.glob("*") do |mod_dir|
+          specfile = "#{mod_dir}/build/pupmod-#{mod_dir}.spec"
+          next if not File.exists?(specfile)
+
+          # Set this to the default...by default.
+          modules[mod_dir] = {
+            :installed => module_default,
+            :info      => Simp::RPM.get_info(specfile)
+          }
+
+          metadata = "#{mod_dir}/build/package_metadata.yaml"
+          if File.exists?(metadata) then
+            modules[mod_dir][:installed] = YAML.load(IO.read(metadata))['optional']
+          end
+        end
+
+      end
+    end
+
+   fh = File.open("#{PUBLICAN_DIR}/en-US/user_guide/SIMP_Package_Data.xml",'w')
+   fh.puts(ERB.new(File.read("#{PUBLICAN_DIR}/en-US/user_guide/SIMP_Package_Data.xml.erb"),nil,'-').result(binding))
+   fh.close
+  end
+
+  def build_rpm_source_appendix
+    # Go dig up the information for the RPMs and create a hash. Right
+    # now, we don't have any way to figure out how to properly
+    # differentiate between the distros at build time.
+    #
+    # This is all hard coded, which is bad, but meh...
+    # TODO: Fix me
+    rpm_info = {
+      'Ext_RHEL' => {},
+      'Ext_CentOS' => {},
+      'Ext_Common' => {}
+    }
+
+    stubbin_time = false
+    if not File.directory?(BUILD_DIR) then
+      $stderr.puts("Warning: Could not find the build directory '#{BUILD_DIR}'. Skipping RPM source appendix")
+      stubbin_time = true
+    else
+      Dir.chdir(BUILD_DIR) do
+        rpm_info.keys.each do |dir|
+          Find.find(dir) do |file|
+            if file =~ /.rpm$/ and file !~ /src.rpm$/ then
+              if File.exist?("#{BUILD_DIR}/#{file}.source") then
+                rpm_info[dir][File.basename(file)] = File.read("#{BUILD_DIR}/#{file}.source").chomp
+              else
+                rpm_info[dir][File.basename(file)] = "Source Unknown - To be corrected"
+              end
+            end
+          end
+        end
+      end
+    end
+
+    # Here's a lovely bunch of crap for dumping the RPM list into
+    # the Appendix_RPM.xml
+    fh = File.open("#{PUBLICAN_DIR}/en-US/security_conop/Appendix_RPM.xml",'w')
+    fh.puts(ERB.new(File.read("#{PUBLICAN_DIR}/en-US/security_conop/Appendix_RPM.xml.erb"),nil,'-').result(binding))
+    fh.close
+
+  end
+
+  def recursive_uptodate?(dest,src)
+    raise(Exception,"Error: Cannot recursively check dates on non-existent file '#{src}'") unless File.exist?(src)
+    return false unless File.exist?(dest)
+
+    src_files = []
+    dest_files = []
+
+    Find.find(src) do |x|
+      src_files << File.stat(x).mtime
+    end
+    Find.find(dest) do |x|
+      dest_files << File.stat(x).mtime
+    end
+
+    return src_files.last == dest_files.last
+  end
+
+end

build/rake_helpers/rdoc.rake

@@ -0,0 +1,67 @@
+# Puppet doc specific tasks
+namespace :rdoc do
+
+  verbose(false)
+
+  module_dir = File.expand_path(File.dirname(__FILE__) + '/../puppet/modules')
+  basedir = File.expand_path(File.dirname(__FILE__) + '/../../')
+
+  task :clean do
+    FileUtils.rm_rf('html/developers_guide/rdoc')
+  end
+
+  desc <<-EOM
+    Builds the SIMP API documentation.
+
+    This is not yet incorporated into the PDF but will be in the future.
+  EOM
+  task :build do
+    tmpdir = "/tmp/simp_puppetdoc_#{Time.now.hash}"
+    if File.exists?(tmpdir) then
+      FileUtils.rm_rf(tmpdir, :secure => true)
+    end
+    FileUtils.mkdir(tmpdir)
+
+    # For this to work properly, some files need to stubbed
+    Dir.chdir(tmpdir) do
+      FileUtils.touch('config')
+      FileUtils.mkdir('manifests')
+      FileUtils.mkdir('modules')
+
+      # Link in all of the modules.
+      Dir.chdir('modules') do
+        Dir.glob("#{module_dir}/*") do |dir|
+          if File.directory?(dir) then
+            FileUtils.mkdir(File.basename(dir))
+            Dir.chdir(File.basename(dir)) do
+              FileUtils.ln_s("#{dir}/lib",'lib') if File.exist?("#{dir}/lib")
+              FileUtils.ln_s("#{dir}/manifests",'manifests') if File.exist?("#{dir}/manifests")
+            end
+          end
+        end
+      end
+
+      begin
+        sh %{puppet doc --all --mode rdoc --outputdir rdoc --modulepath modules --manifestdir manifests --config config}
+      ensure
+        if (Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('1.9')) then
+          # In Ruby > 1.8.7, crufty _pp.html files are left all over the place.
+          sh %{find -L modules -type f \\( -name "*_pp.html" -o -name "*rb.html" \\) -exec rm \{\} \\;}
+        end
+      end
+
+      FileUtils.cp_r("rdoc/","#{basedir}/html/developers_guide/")
+    end
+
+    # Remove empty cruft
+    FileUtils.rm_rf("#{basedir}/html/developers_guide/rdoc/files/tmp")
+
+    # Now, we have to go through and reassign everything to the real system file location.
+    # No, this isn't portable, but most of this isn't so we're not going to
+    # worry about purity right now.
+    sh %{find #{basedir}/html/developers_guide/rdoc -name "*.html" -exec sed -i 's|\\(\\.\\./\\?\\)\\+/files/tmp/simp_puppetdoc_[[:digit:]]\\+\\(.*\\)_pp\\.html|file:///etc/puppet\\2.pp|g' {} \\;}
+    sh %{find #{basedir}/html/developers_guide/rdoc -name "*.html" -exec sed -i 's|/tmp/simp_puppetdoc_[[:digit:]]\\+|/etc/puppet|g' {} \\;}
+
+    FileUtils.rm_rf(tmpdir, :secure => true)
+  end
+end