From f1c166c9bd152ad63482d3f6fd21ba3c3022b6c8 Mon Sep 17 00:00:00 2001 From: Martin Alfke Date: Sat, 25 Apr 2026 13:03:23 +0200 Subject: [PATCH 1/2] Deploy autogenerated docs This solution is not able to deal with multiple versions. VERSION can be omitted, using the latest tag INSTALLPATH is only used upon build action to place autogeneraed into the correct location. Signed-off-by: Martin Alfke --- .github/workflows/build.yaml | 2 ++ Rakefile | 16 ++++++++++------ _config.yml | 1 + lib/puppet_references.rb | 15 ++++++++++----- lib/puppet_references/facter/core_facts.rb | 2 +- lib/puppet_references/facter/facter_cli.rb | 2 +- lib/puppet_references/puppet/functions.rb | 2 +- lib/puppet_references/puppet/http.rb | 2 +- lib/puppet_references/puppet/man.rb | 2 +- lib/puppet_references/puppet/puppet_doc.rb | 2 +- lib/puppet_references/puppet/strings.rb | 2 +- lib/puppet_references/puppet/type.rb | 4 ++-- lib/puppet_references/puppet/type_strings.rb | 5 +++-- lib/puppet_references/puppet/yard.rb | 2 +- lib/puppet_references/repo.rb | 5 +++++ 15 files changed, 41 insertions(+), 23 deletions(-) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index f0eeaf0ac..f6bc17819 100644 --- a/.github/workflows/build.yaml +++ b/.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: | diff --git a/Rakefile b/Rakefile index fa86129ee..d54bb4bdb 100644 --- a/Rakefile +++ b/Rakefile @@ -28,18 +28,20 @@ CLOBBER.include('references_output') desc 'List the available groups of references. Run `rake references:` to build.' task :references do puts 'The following references are available:' - puts 'bundle exec rake references:openvox VERSION=' - puts 'bundle exec rake references:openfact VERSION=' + puts 'bundle exec rake references:openvox [VERSION= INSTALLPATH=]' + puts 'bundle exec rake references:openfact [VERSION= INSTALLPATH=]' 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 diff --git a/_config.yml b/_config.yml index a540fbe0d..d4f68e959 100644 --- a/_config.yml +++ b/_config.yml @@ -128,3 +128,4 @@ exclude: - util - vendor - WORKFLOW.md + - WORKFLOW_reference.md diff --git a/lib/puppet_references.rb b/lib/puppet_references.rb index 2fe84011e..73e1c73f9 100644 --- a/lib/puppet_references.rb +++ b/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 diff --git a/lib/puppet_references/facter/core_facts.rb b/lib/puppet_references/facter/core_facts.rb index 78a086622..e3e6a72a7 100644 --- a/lib/puppet_references/facter/core_facts.rb +++ b/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 diff --git a/lib/puppet_references/facter/facter_cli.rb b/lib/puppet_references/facter/facter_cli.rb index 1626e43e1..b3723ec9b 100644 --- a/lib/puppet_references/facter/facter_cli.rb +++ b/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 diff --git a/lib/puppet_references/puppet/functions.rb b/lib/puppet_references/puppet/functions.rb index c9f34e931..c34089088 100644 --- a/lib/puppet_references/puppet/functions.rb +++ b/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 diff --git a/lib/puppet_references/puppet/http.rb b/lib/puppet_references/puppet/http.rb index 6da40b78d..b6d5ed4b5 100644 --- a/lib/puppet_references/puppet/http.rb +++ b/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' diff --git a/lib/puppet_references/puppet/man.rb b/lib/puppet_references/puppet/man.rb index 02dc36ecd..2356308f7 100644 --- a/lib/puppet_references/puppet/man.rb +++ b/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' diff --git a/lib/puppet_references/puppet/puppet_doc.rb b/lib/puppet_references/puppet/puppet_doc.rb index 78e9ea5db..a727f6ee3 100644 --- a/lib/puppet_references/puppet/puppet_doc.rb +++ b/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' diff --git a/lib/puppet_references/puppet/strings.rb b/lib/puppet_references/puppet/strings.rb index 7d30cc01e..325445a91 100644 --- a/lib/puppet_references/puppet/strings.rb +++ b/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) diff --git a/lib/puppet_references/puppet/type.rb b/lib/puppet_references/puppet/type.rb index c56a86c3d..f6e702490 100644 --- a/lib/puppet_references/puppet/type.rb +++ b/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 diff --git a/lib/puppet_references/puppet/type_strings.rb b/lib/puppet_references/puppet/type_strings.rb index 04c8a0167..0bd1edb40 100644 --- a/lib/puppet_references/puppet/type_strings.rb +++ b/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'], diff --git a/lib/puppet_references/puppet/yard.rb b/lib/puppet_references/puppet/yard.rb index 3abc65874..65563bfed 100644 --- a/lib/puppet_references/puppet/yard.rb +++ b/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' diff --git a/lib/puppet_references/repo.rb b/lib/puppet_references/repo.rb index 12edac013..634f7d129 100644 --- a/lib/puppet_references/repo.rb +++ b/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 From f535ae706ba93f328426fd8e6a909646fc0d3f0c Mon Sep 17 00:00:00 2001 From: Martin Alfke Date: Sat, 25 Apr 2026 15:05:55 +0200 Subject: [PATCH 2/2] Use rake to generate references Signed-off-by: Martin Alfke --- .github/workflows/build.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index f6bc17819..d783f33c9 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -75,8 +75,8 @@ jobs: - name: Build website run: | - bundle exec references:openfact INSTALLPATH=docs - bundle exec references:openvox INSTALLPATH=docs + bundle exec rake references:openfact INSTALLPATH=docs + bundle exec rake references:openvox INSTALLPATH=docs bundle exec jekyll build - name: Archive website run: |