Deploy autogenerated docs

.github/workflows/build.yaml

@@ -75,6 +75,8 @@ jobs:
 
       - name: Build website
         run: |
+          bundle exec references:openfact INSTALLPATH=docs
+          bundle exec references:openvox INSTALLPATH=docs
           bundle exec jekyll build
       - name: Archive website
         run: |

Rakefile

@@ -28,18 +28,20 @@ CLOBBER.include('references_output')
 desc 'List the available groups of references. Run `rake references:<GROUP>` to build.'
 task :references do
   puts 'The following references are available:'
-  puts 'bundle exec rake references:openvox VERSION=<GIT TAG OR COMMIT>'
-  puts 'bundle exec rake references:openfact VERSION=<GIT TAG OR COMMIT>'
+  puts 'bundle exec rake references:openvox [VERSION=<GIT TAG OR COMMIT> INSTALLPATH=<RELATIVE OR ABSOLUTE PATH>]'
+  puts 'bundle exec rake references:openfact [VERSION=<GIT TAG OR COMMIT> INSTALLPATH=<RELATIVE OR ABSOLUTE PATH>]'
   puts 'bundle exec rake references:version_tables'
+  puts '  VERSION can be omitted, uses latest tag'
+  puts '  INSTALLPATH can be omitted, defaults to references_output/'
 end
 
 namespace :references do
-  task openvox: 'references:check_version' do
+  task openvox: 'references:check' do
     require 'puppet_references'
     PuppetReferences.build_puppet_references(ENV.fetch('VERSION', nil))
   end
 
-  task openfact: 'references:check_version' do
+  task openfact: 'references:check' do
     require 'puppet_references'
     PuppetReferences.build_facter_references(ENV.fetch('VERSION', nil))
   end
@@ -49,7 +51,9 @@ namespace :references do
     PuppetReferences.build_version_tables
   end
 
-  task :check_version do
-    abort 'No VERSION given to build references for' unless ENV['VERSION']
+  task :check do
+    puts 'No VERSION given to build references for - using latest tag' unless ENV['VERSION']
+    puts "Using provided install path #{ENV.fetch('INSTALLPATH')} instead of default" if ENV['INSTALLPATH']
+    puts "Using default install path 'references_output'" unless ENV['INSTALLPATH']
   end
 end

_config.yml

@@ -128,3 +128,4 @@ exclude:
   - util
   - vendor
   - WORKFLOW.md
+  - WORKFLOW_reference.md

lib/puppet_references.rb

@@ -7,7 +7,8 @@ module PuppetReferences
   PUPPET_DIR = BASE_DIR + 'vendor/openvox'
   FACTER_DIR = BASE_DIR + 'vendor/openfact'
   AGENT_DIR = BASE_DIR + 'vendor/openvox-agent'
-  OUTPUT_DIR = BASE_DIR + 'references_output'
+  INSTALLPATH = ENV['INSTALLPATH'] ? ENV.fetch('INSTALLPATH') : 'references_output'
+  OUTPUT_DIR = BASE_DIR + INSTALLPATH
 
   require 'puppet_references/config'
   require 'puppet_references/util'
@@ -37,7 +38,9 @@ def self.build_puppet_references(commit)
     ]
     config = PuppetReferences::Config.read
     repo = PuppetReferences::Repo.new('openvox', PUPPET_DIR, nil, config['puppet']['repo'])
-    real_commit = repo.checkout(commit)
+    version_commit = commit || repo.describe.split('-')[0]
+    puts "Using tag #{version_commit}"
+    real_commit = repo.checkout(version_commit)
     repo.update_bundle
     build_from_list_of_classes(references, real_commit)
   end
@@ -54,11 +57,13 @@ def self.build_facter_references(commit)
     # we need the CLI docs for 3.y. We can remove this when we stop building 3.y.
     version4 = Gem::Version.create('4.0.0')
     repo = PuppetReferences::Repo.new('openfact', FACTER_DIR)
-    real_commit = repo.checkout(commit)
+    version_commit = commit || repo.describe.split('-')[0]
+    puts "Using tag #{version_commit}"
+    real_commit = repo.checkout(version_commit)
     repo.update_bundle
-    if !semantic?(commit) || (semantic?(commit) && Gem::Version.create(commit) >= version4)
+    if !semantic?(version_commit) || (semantic?(version_commit) && Gem::Version.create(version_commit) >= version4)
       references << PuppetReferences::Facter::FacterCli
-    elsif semantic?(commit) && Gem::Version.create(commit) < version4
+    elsif semantic?(version_commit) && Gem::Version.create(version_commit) < version4
       reference = PuppetReferences::Facter::FacterCli.new(real_commit)
       reference.build_v3_cli
     end

lib/puppet_references/facter/core_facts.rb

@@ -4,7 +4,7 @@
 module PuppetReferences
   module Facter
     class CoreFacts < PuppetReferences::Reference
-      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + 'openfact'
+      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + '_openfact_latest'
       PREAMBLE_FILE = Pathname.new(__FILE__).dirname + 'core_facts_preamble.md'
       PREAMBLE = PREAMBLE_FILE.read
 

lib/puppet_references/facter/facter_cli.rb

@@ -4,7 +4,7 @@
 module PuppetReferences
   module Facter
     class FacterCli < PuppetReferences::Reference
-      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + 'openfact'
+      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + '_openfact_latest'
       PREAMBLE_FILE = Pathname.new(__FILE__).dirname + 'facter_cli_preamble.md'
       PREAMBLE = PREAMBLE_FILE.read
 

lib/puppet_references/puppet/functions.rb

@@ -10,7 +10,7 @@ module PuppetReferences
   module Puppet
     class Functions < PuppetReferences::Reference
       TEMPLATE_FILE = Pathname.new(File.expand_path(__FILE__)).dirname + 'functions_template.erb'
-      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + 'openvox'
+      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + '_openvox_latest'
       PREAMBLE_FILE = Pathname.new(File.expand_path(__FILE__)).dirname + 'functions_preamble.md'
       PREAMBLE = PREAMBLE_FILE.read
 

lib/puppet_references/puppet/http.rb

@@ -5,7 +5,7 @@
 module PuppetReferences
   module Puppet
     class Http < PuppetReferences::Reference
-      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + 'openvox'
+      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + '_openvox_latest'
       DOCS_DIR = OUTPUT_DIR + 'http_api'
       API_SOURCE = PuppetReferences::PUPPET_DIR + 'api'
 

lib/puppet_references/puppet/man.rb

@@ -5,7 +5,7 @@
 module PuppetReferences
   module Puppet
     class Man < PuppetReferences::Reference
-      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + 'openvox/man'
+      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + '_openvox_latest/man'
 
       def initialize(*)
         @latest = '/openvox/latest/man'

lib/puppet_references/puppet/puppet_doc.rb

@@ -5,7 +5,7 @@ module PuppetReferences
   module Puppet
     class PuppetDoc < PuppetReferences::Reference
       REFERENCES = %w[configuration].freeze
-      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + 'openvox'
+      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + '_openvox_latest'
 
       def initialize(*)
         @latest = '/openvox/latest'

lib/puppet_references/puppet/strings.rb

@@ -8,7 +8,7 @@
 module PuppetReferences
   module Puppet
     class Strings < Hash
-      STRINGS_JSON_FILE = PuppetReferences::OUTPUT_DIR + 'openvox/strings.json'
+      STRINGS_JSON_FILE = PuppetReferences::OUTPUT_DIR + '_openvox_latest/strings.json'
       @@strings_data_cached = false
 
       def initialize(force_cached: false)

lib/puppet_references/puppet/type.rb

@@ -16,8 +16,8 @@ class Type < PuppetReferences::Reference
 
       def initialize(*)
         @latest = '/openvox/latest'
-        @output_dir_unified = PuppetReferences::OUTPUT_DIR + 'openvox'
-        @output_dir_individual = PuppetReferences::OUTPUT_DIR + 'openvox/types'
+        @output_dir_unified = PuppetReferences::OUTPUT_DIR + '_openvox_latest'
+        @output_dir_individual = PuppetReferences::OUTPUT_DIR + '_openvox_latest/types'
         @base_filename = 'type'
         super
       end

lib/puppet_references/puppet/type_strings.rb

@@ -7,7 +7,8 @@ module Puppet
     class TypeStrings < PuppetReferences::Puppet::Type
       def initialize(*)
         super
-        @output_dir_individual = PuppetReferences::OUTPUT_DIR + 'openvox/types_strings'
+        @output_dir_individual = PuppetReferences::OUTPUT_DIR + '_openvox_latest/types_strings'
+        @output_dir = PuppetReferences::OUTPUT_DIR + '_openvox_latest'
         @base_filename = 'type_strings'
       end
 
@@ -16,7 +17,7 @@ def get_type_json
         # 2. Munge it to match the old format I threw together, which the template uses.
         # 3. Dump result to JSON.
         strings_data = PuppetReferences::Puppet::Strings.new
-        File.write('references_output/openvox/raw_strings_data_output.json', strings_data)
+        File.write("#{@output_dir}/raw_strings_data_output.json", strings_data)
         type_hash = strings_data['resource_types'].each_with_object({}) do |type, memo|
           memo[ type['name'] ] = {
             'description' => type['docstring']['text'],

lib/puppet_references/puppet/yard.rb

@@ -4,7 +4,7 @@
 module PuppetReferences
   module Puppet
     class Yard < PuppetReferences::Reference
-      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + 'openvox/yard'
+      OUTPUT_DIR = PuppetReferences::OUTPUT_DIR + '_openvox_latest/yard'
 
       def initialize(*)
         @latest = '/openvox/latest/yard'

lib/puppet_references/repo.rb

@@ -23,6 +23,7 @@ def initialize(name, directory, sources = nil, config = nil)
         puts 'done cloning.'
       end
       @repo = Git.open(@directory)
+      @repo.checkout('remotes/origin/HEAD')
       # fetch the main source
       @repo.fetch unless @config['skip_download']
       # fetch tags from secondary sources
@@ -36,6 +37,10 @@ def checkout(commit)
       @repo.revparse(commit)
     end
 
+    def describe
+      @repo.describe
+    end
+
     def tags
       @repo.tags
     end