(FACT-2708) Add man pages

Gemfile

@@ -10,3 +10,7 @@ end
 
 local_gemfile = File.expand_path('Gemfile.local', __dir__)
 eval_gemfile(local_gemfile) if File.exist?(local_gemfile)
+
+group(:documentation) do
+  gem 'ronn', '~> 0.7.3', require: false, platforms: [:ruby]
+end

agent/facter-ng.gemspec

@@ -18,7 +18,8 @@ Gem::Specification.new do |spec|
                Dir['lib/**/*.rb'] +
                Dir['lib/**/*.json'] +
                Dir['lib/**/*.conf'] +
-               Dir['agent/**/*']
+               Dir['agent/**/*'] +
+               Dir['lib/**/*.erb']
 
   spec.required_ruby_version = '~> 2.3'
 

facter.gemspec

@@ -17,7 +17,8 @@ Gem::Specification.new do |spec|
   spec.files = Dir['bin/facter'] +
                Dir['lib/**/*.rb'] +
                Dir['lib/**/*.json'] +
-               Dir['lib/**/*.conf']
+               Dir['lib/**/*.conf'] +
+               Dir['lib/**/*.erb']
 
   spec.required_ruby_version = '~> 2.3'
   spec.bindir = 'bin'

install.rb

@@ -126,11 +126,11 @@ def prepare_installation
               'overrides RbConfig::CONFIG["sitelibdir"]') do |sitelibdir|
         InstallOptions.sitelibdir = sitelibdir
       end
-      # opts.on('--mandir[=OPTIONAL]',
-      #         'Installation directory for man pages',
-      #          'overrides RbConfig::CONFIG["mandir"]') do |mandir|
-      #   InstallOptions.mandir = mandir
-      # end
+      opts.on('--mandir[=OPTIONAL]',
+              'Installation directory for man pages',
+              'overrides RbConfig::CONFIG["mandir"]') do |mandir|
+        InstallOptions.mandir = mandir
+      end
       opts.on('--full', 'Performs a full installation. All', 'optional installation steps are run.') do |_full|
         InstallOptions.configs = true
       end
@@ -182,30 +182,26 @@ def prepare_installation
       end
     end
 
-    # if InstallOptions.mandir
-    #   mandir = InstallOptions.mandir
-    # else
-    #   mandir = RbConfig::CONFIG['mandir']
-    # end
+    mandir = InstallOptions.mandir || RbConfig::CONFIG['mandir']
 
     # This is the new way forward
     destdir = InstallOptions.destdir || ''
 
     # configdir = join(destdir, configdir)
     bindir = join(destdir, bindir)
-    # mandir = join(destdir, mandir)
+    mandir = join(destdir, mandir)
     sitelibdir = join(destdir, sitelibdir)
 
     # makedirs(configdir) if InstallOptions.configs
     makedirs(bindir)
-    # makedirs(mandir)
+    makedirs(mandir)
     makedirs(sitelibdir)
 
     InstallOptions.site_dir = sitelibdir
     # InstallOptions.config_dir = configdir
     InstallOptions.bin_dir  = bindir
     InstallOptions.lib_dir  = libdir
-    # InstallOptions.man_dir  = mandir
+    InstallOptions.man_dir  = mandir
   end
 
   ##
@@ -281,12 +277,14 @@ def run
     cd File.dirname(__FILE__) do
       # Set these values to what you want installed.
       bins  = glob(%w[bin/facter])
-      libs  = glob(%w[lib/**/*.rb lib/facter/os_hierarchy.json lib/facter/fact_groups.conf])
+      libs  = glob(%w[lib/**/*.rb lib/facter/os_hierarchy.json lib/facter/fact_groups.conf lib/facter/templates/*])
+      man   = glob(%w{man/man[0-9]/*})
 
       prepare_installation
 
       do_bins(bins, InstallOptions.bin_dir)
       do_libs(libs)
+      do_man(man) unless windows?
     end
   end
 end

lib/facter/framework/cli/cli.rb

@@ -35,6 +35,11 @@ class Cli < Thor
                  type: :boolean,
                  desc: 'Print this help message.'
 
+    class_option :man,
+                 hide: true,
+                 type: :boolean,
+                 desc: 'Display manual.'
+
     class_option :hocon,
                  type: :boolean,
                  desc: 'Output in Hocon format.'
@@ -103,6 +108,18 @@ class Cli < Thor
                  aliases: '-p',
                  desc: 'Load the Puppet libraries, thus allowing Facter to load Puppet-specific facts.'
 
+    desc '--man', 'Manual', hide: true
+    map ['--man'] => :man
+    def man(*args)
+      require 'erb'
+      negate_options = %w[block cache custom_facts external_facts]
+
+      template = File.join(File.dirname(__FILE__), '..', '..', 'templates', 'man.erb')
+      erb = ERB.new(File.read(template), nil, '-')
+      erb.filename = template
+      puts erb.result(binding)
+    end
+
     desc 'query', 'Default method', hide: true
     desc '[options] [query] [query] [...]', ''
     def query(*args)
@@ -119,13 +136,13 @@ def version
       puts Facter::VERSION
     end
 
-    desc '--list-block-groups', 'List block groups'
+    desc '--list-block-groups', 'List block groups', hide: true
     map ['--list-block-groups'] => :list_block_groups
     def list_block_groups(*_args)
       puts Facter::FactGroups.new.groups.to_yaml.lines[1..-1].join
     end
 
-    desc '--list-cache-groups', 'List cache groups'
+    desc '--list-cache-groups', 'List cache groups', hide: true
     map ['--list-cache-groups'] => :list_cache_groups
     def list_cache_groups(*_args)
       puts Facter::FactGroups.new.groups.to_yaml.lines[1..-1].join

lib/facter/templates/man.erb

@@ -0,0 +1,122 @@
+<%# encoding: UTF-8%>
+SYNOPSIS
+--------
+  facter [options] [query] [query] [...]
+
+DESCRIPTION
+-----------
+Collect and display facts about the current system. The library behind Facter is easy to extend, making Facter an easy way to collect information about a system.
+
+If no queries are given, then all facts will be returned.
+
+Many of the command line options can also be set via the HOCON config file. This file can also be used to block or cache certain fact groups.
+
+OPTIONS
+-------
+<% @Facter::Cli.class_options.each do |name, option| -%><% next if option.hide%>
+  * `<%= option.aliases[0] + '`, `' if option.aliases.any? %>--<%= 'no-' if negate_options.include?(name.to_s)%><%= name.to_s.gsub('_','-') %>`:
+
+    <%= option.description %>
+
+<% end -%>
+
+FILES
+-----
+<em>/etc/puppetlabs/facter/facter.conf</em>
+
+A HOCON config file that can be used to specify directories for custom and external facts, set various command line options, and specify facts to block. See example below for details, or visit the GitHub README.
+
+EXAMPLES
+--------
+Display all facts:
+
+```
+$ facter
+disks => {
+  sda => {
+    model => "Virtual disk",
+    size => "8.00 GiB",
+    size_bytes => 8589934592,
+    vendor => "ExampleVendor"
+  }
+}
+dmi => {
+  bios => {
+    release_date => "06/23/2013",
+    vendor => "Example Vendor",
+    version => "6.00"
+  }
+}
+[\.\.\.]
+```
+
+Display a single structured fact:
+
+```
+$ facter processors
+{
+  count => 2,
+  isa => "x86_64",
+  models => [
+    "Intel(R) Xeon(R) CPU E5-2680 v2 @ 2.80GHz",
+    "Intel(R) Xeon(R) CPU E5-2680 v2 @ 2.80GHz"
+  ],
+  physicalcount => 2
+}
+```
+
+Display a single fact nested within a structured fact:
+
+```
+$ facter processors.isa
+x86_64
+```
+
+Display a single legacy fact. Note that non-structured facts existing in previous versions of Facter are still available,
+but are not displayed by default due to redundancy with newer structured facts:
+
+```
+$ facter processorcount
+2
+```
+
+Format facts as JSON:
+
+```
+$ facter \-\-json os.name os.release.major processors.isa
+{
+  "os.name": "Ubuntu",
+  "os.release.major": "14.04",
+  "processors.isa": "x86_64"
+}
+```
+
+An example config file.
+
+```
+# always loaded (CLI and as Ruby module)
+global : {
+    external-dir : "~/external/facts",
+    custom-dir   :  [
+       "~/custom/facts",
+       "~/custom/facts/more-facts"
+    ],
+    no-external-facts : false,
+    no-custom-facts   : false,
+    no-ruby           : false
+}
+# loaded when running from the command line
+cli : {
+    debug     : false,
+    trace     : true,
+    verbose   : false,
+    log-level : "info"
+}
+# always loaded, fact-sepcific configuration
+facts : {
+    # for valid blocklist entries, use --list-block-groups
+    blocklist : [ "file system", "EC2" ],
+    # for valid time-to-live entries, use --list-cache-groups
+    ttls : [ { "timezone" : 30 days } ]
+}
+```