Merge pull request #1075 from puppetlabs/pandoc-man-pages

Use Pandoc to generate man files

Author: Heston Hoffman

Gemfile

@@ -19,6 +19,7 @@ group(:generate_references) do
   gem 'yard', '~> 0.9'
   gem 'rdoc', '~> 6.2'
   gem 'rgen', '~> 0.8'
+  gem 'pandoc-ruby'
   gem 'puppet-strings'
   gem 'puppet', '~> 6'
   gem 'nokogiri', '~> 1.11'

Gemfile.lock

@@ -82,6 +82,7 @@ GEM
     nokogiri (1.11.4-x86_64-darwin)
       racc (~> 1.4)
     open4 (1.3.4)
+    pandoc-ruby (2.1.4)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     pragmatic_segmenter (0.3.23)
@@ -166,6 +167,7 @@ DEPENDENCIES
   listen (~> 3.5.1)
   maruku (~> 0.7)
   nokogiri (~> 1.11)
+  pandoc-ruby
   pragmatic_segmenter (~> 0.3)
   punkt-segmenter (~> 0.9)
   puppet (~> 6)
@@ -179,4 +181,3 @@ DEPENDENCIES
   vlad (~> 2.7)
   vlad-git (~> 2.1)
   yard (~> 0.9)
-  

lib/puppet_references.rb

@@ -54,9 +54,14 @@ def self.build_facter_references(commit)
     # Adding this workaround so the build doesn't fail for 3.y. Check with Claire to see if
     # we need the CLI docs for 3.y. We can remove this when we stop building 3.y.
     version_4 = Gem::Version.create('4.0.0')
-    references << PuppetReferences::Facter::FacterCli if !is_semantic?(commit) || !is_semantic?(commit) && Gem::Version.create(commit) >= version_4
     repo = PuppetReferences::Repo.new('facter', FACTER_DIR)
     real_commit = repo.checkout(commit)
+    if !is_semantic?(commit) || is_semantic?(commit) && Gem::Version.create(commit) >= version_4
+      references << PuppetReferences::Facter::FacterCli
+    elsif is_semantic?(commit) && Gem::Version.create(commit) < version_4
+      reference = PuppetReferences::Facter::FacterCli.new(real_commit)
+      reference.build_v3_cli
+    end
     build_from_list_of_classes(references, real_commit)
   end
 

lib/puppet_references/facter/facter_cli.rb

@@ -11,6 +11,14 @@ def initialize(*args)
         super(*args)
       end
 
+
+      def header_data
+        {title: 'Facter: CLI',
+         toc: 'columns',
+         canonical: "#{@latest}/cli.html"}
+      end
+
+
       def build_all
         require 'open3'
         puts 'Building CLI documentation page for facter.'
@@ -23,15 +31,20 @@ def build_all
           puts "Encountered an error while building the facter cli docs, will abort: #{err}"
           return
         end
-
-        header_data = {title: 'Facter: CLI',
-                       toc: 'columns',
-                       canonical: "#{@latest}/cli.html"}
         content = make_header(header_data) + PREAMBLE + raw_text
         filename = OUTPUT_DIR + 'cli.md'
         filename.open('w') {|f| f.write(content)}
         puts 'CLI documentation is done!'
       end
-    end
+
+      def build_v3_cli
+        filename = OUTPUT_DIR + 'cli.md'
+        man_filepath = PuppetReferences::FACTER_DIR + 'man/man8/facter.8'
+        raw_text = PuppetReferences::Util.convert_man(man_filepath)
+        content = make_header(header_data) + raw_text
+        filename.open('w') {|f| f.write(content)}
+      end 
+
+    end 
   end
 end

lib/puppet_references/puppet/man.rb

@@ -115,16 +115,13 @@ def get_subcommands
         applications
       end
 
-      def code_wrap(raw_text)
-        "<pre><code>" + raw_text.gsub('<','&lt;').gsub('>','&gt;') + "</code></pre>"
-      end
-
       def build_manpage(subcommand)
         puts "Man pages: Building #{subcommand}"
         header_data = {title: "Man Page: puppet #{subcommand}",
                        canonical: "#{@latest}/#{subcommand}.html"}
-        raw_text = PuppetReferences::ManCommand.new(subcommand).get
-        content = make_header(header_data) + code_wrap(raw_text)
+        # raw_text = PuppetReferences::ManCommand.new(subcommand).get
+        man_filepath = "#{PuppetReferences::PUPPET_DIR}" + "/man/man8/puppet-#{subcommand}.8"
+        content = make_header(header_data) + PuppetReferences::Util.convert_man(man_filepath)
         filename = OUTPUT_DIR + "#{subcommand}.md"
         filename.open('w') {|f| f.write(content)}
       end

lib/puppet_references/util.rb

@@ -120,5 +120,13 @@ def self.link_release_notes_if_applicable(component, text, version = nil, agent_
       end
     end
 
+    def self.convert_man(man_filepath)
+      require 'pandoc-ruby'
+      PandocRuby.convert([man_filepath], from: :man, to: :markdown)
+        .gsub(/#(.*?)\n/, '##\1')
+        .gsub(/:\s\s\s\n\n```\{=html\}\n<!--\s-->\n```/, '')
+        .gsub(/\n:\s\s\s\s/, '')
+    end
+
   end
 end