From 0911a3d128e81d279effe6cd6520603074d53757 Mon Sep 17 00:00:00 2001 From: Steven Pritchard Date: Sun, 22 Feb 2026 00:04:02 +0000 Subject: [PATCH] Remove puppet doc command The puppet doc command has been removed as deprecated. Co-Authored-By: Claude Sonnet 4.6 --- lib/puppet/application/doc.rb | 232 ---------------- man/man8/puppet-doc.8 | 30 -- spec/integration/application/doc_spec.rb | 34 --- spec/unit/application/doc_spec.rb | 333 ----------------------- 4 files changed, 629 deletions(-) delete mode 100644 lib/puppet/application/doc.rb delete mode 100644 man/man8/puppet-doc.8 delete mode 100644 spec/integration/application/doc_spec.rb delete mode 100644 spec/unit/application/doc_spec.rb diff --git a/lib/puppet/application/doc.rb b/lib/puppet/application/doc.rb deleted file mode 100644 index 679e2069c4..0000000000 --- a/lib/puppet/application/doc.rb +++ /dev/null @@ -1,232 +0,0 @@ -# frozen_string_literal: true - -require_relative '../../puppet/application' - -class Puppet::Application::Doc < Puppet::Application - run_mode :server - - attr_accessor :unknown_args, :manifest - - def preinit - { :references => [], :mode => :text, :format => :to_markdown }.each do |name, value| - options[name] = value - end - @unknown_args = [] - @manifest = false - end - - option("--all", "-a") - option("--outputdir OUTPUTDIR", "-o") - option("--verbose", "-v") - option("--debug", "-d") - option("--charset CHARSET") - - option("--format FORMAT", "-f") do |arg| - method = "to_#{arg}" - require_relative '../../puppet/util/reference' - if Puppet::Util::Reference.method_defined?(method) - options[:format] = method - else - raise _("Invalid output format %{arg}") % { arg: arg } - end - end - - option("--mode MODE", "-m") do |arg| - require_relative '../../puppet/util/reference' - if Puppet::Util::Reference.modes.include?(arg) or arg.intern == :rdoc - options[:mode] = arg.intern - else - raise _("Invalid output mode %{arg}") % { arg: arg } - end - end - - option("--list", "-l") do |_arg| - require_relative '../../puppet/util/reference' - refs = Puppet::Util::Reference.references(Puppet.lookup(:current_environment)) - puts refs.collect { |r| Puppet::Util::Reference.reference(r).doc }.join("\n") - exit(0) - end - - option("--reference REFERENCE", "-r") do |arg| - options[:references] << arg.intern - end - - def summary - _("Generate Puppet references for OpenVox") - end - - def help - <<~HELP - - puppet-doc(8) -- #{summary} - ======== - - SYNOPSIS - -------- - Generates a reference for all Puppet types. Largely meant for internal use. (Deprecated) - - - USAGE - ----- - puppet doc [-h|--help] [-l|--list] - [-r|--reference ] - - - DESCRIPTION - ----------- - This deprecated command generates a Markdown document to stdout - describing all installed Puppet types or all allowable arguments to - puppet executables. It is largely meant for internal use and is used to - generate the reference documents which can be posted to a website. - - For Puppet module documentation (and all other use cases) this command - has been superseded by the "puppet-strings" - module - see https://github.com/puppetlabs/puppetlabs-strings for more information. - - This command (puppet-doc) will be removed once the - puppetlabs internal documentation processing pipeline is completely based - on puppet-strings. - - OPTIONS - ------- - - * --help: - Print this help message - - * --reference: - Build a particular reference. Get a list of references by running - 'puppet doc --list'. - - - EXAMPLE - ------- - $ puppet doc -r type > /tmp/type_reference.markdown - - - AUTHOR - ------ - Luke Kanies - - - COPYRIGHT - --------- - Copyright (c) 2011 Puppet Inc. - Copyright (c) 2024 Vox Pupuli - Licensed under the Apache 2.0 License - - HELP - end - - def handle_unknown(opt, arg) - @unknown_args << { :opt => opt, :arg => arg } - true - end - - def run_command - [:rdoc].include?(options[:mode]) ? send(options[:mode]) : other - end - - def rdoc - exit_code = 0 - files = [] - unless @manifest - env = Puppet.lookup(:current_environment) - files += env.modulepath - files << ::File.dirname(env.manifest) if env.manifest != Puppet::Node::Environment::NO_MANIFEST - end - files += command_line.args - Puppet.info _("scanning: %{files}") % { files: files.inspect } - - Puppet.settings[:document_all] = options[:all] || false - begin - require_relative '../../puppet/util/rdoc' - if @manifest - Puppet::Util::RDoc.manifestdoc(files) - else - options[:outputdir] = "doc" unless options[:outputdir] - Puppet::Util::RDoc.rdoc(options[:outputdir], files, options[:charset]) - end - rescue => detail - Puppet.log_exception(detail, _("Could not generate documentation: %{detail}") % { detail: detail }) - exit_code = 1 - end - exit exit_code - end - - def other - text = ''.dup - with_contents = options[:references].length <= 1 - exit_code = 0 - require_relative '../../puppet/util/reference' - options[:references].sort_by(&:to_s).each do |name| - section = Puppet::Util::Reference.reference(name) - raise _("Could not find reference %{name}") % { name: name } unless section - - begin - # Add the per-section text, but with no ToC - text += section.send(options[:format], with_contents) - rescue => detail - Puppet.log_exception(detail, _("Could not generate reference %{name}: %{detail}") % { name: name, detail: detail }) - exit_code = 1 - next - end - end - - text += Puppet::Util::Reference.footer unless with_contents # We've only got one reference - - puts text - - exit exit_code - end - - def setup - # sole manifest documentation - if command_line.args.size > 0 - options[:mode] = :rdoc - @manifest = true - end - - if options[:mode] == :rdoc - setup_rdoc - else - setup_reference - end - - setup_logging - end - - def setup_reference - if options[:all] - # Don't add dynamic references to the "all" list. - require_relative '../../puppet/util/reference' - refs = Puppet::Util::Reference.references(Puppet.lookup(:current_environment)) - options[:references] = refs.reject do |ref| - Puppet::Util::Reference.reference(ref).dynamic? - end - end - - options[:references] << :type if options[:references].empty? - end - - def setup_rdoc - # consume the unknown options - # and feed them as settings - if @unknown_args.size > 0 - @unknown_args.each do |option| - # force absolute path for modulepath when passed on commandline - if option[:opt] == "--modulepath" - option[:arg] = option[:arg].split(::File::PATH_SEPARATOR).collect { |p| ::File.expand_path(p) }.join(::File::PATH_SEPARATOR) - end - Puppet.settings.handlearg(option[:opt], option[:arg]) - end - end - end - - def setup_logging - Puppet::Util::Log.level = :warning - - set_log_level - - Puppet::Util::Log.newdestination(:console) - end -end diff --git a/man/man8/puppet-doc.8 b/man/man8/puppet-doc.8 deleted file mode 100644 index e29c0d78dc..0000000000 --- a/man/man8/puppet-doc.8 +++ /dev/null @@ -1,30 +0,0 @@ -.\" generated with Ronn-NG/v0.10.1 -.\" http://github.com/apjanke/ronn-ng/tree/0.10.1 -.TH "PUPPET\-DOC" "8" "January 2025" "Vox Pupuli" "OpenVox manual" -.SH "NAME" -\fBpuppet\-doc\fR \- Generate Puppet references for OpenVox -.SH "SYNOPSIS" -Generates a reference for all Puppet types\. Largely meant for internal use\. (Deprecated) -.SH "USAGE" -puppet doc [\-h|\-\-help] [\-l|\-\-list] [\-r|\-\-reference \fIreference\-name\fR] -.SH "DESCRIPTION" -This deprecated command generates a Markdown document to stdout describing all installed Puppet types or all allowable arguments to puppet executables\. It is largely meant for internal use and is used to generate the reference documents which can be posted to a website\. -.P -For Puppet module documentation (and all other use cases) this command has been superseded by the "puppet\-strings" module \- see https://github\.com/puppetlabs/puppetlabs\-strings for more information\. -.P -This command (puppet\-doc) will be removed once the puppetlabs internal documentation processing pipeline is completely based on puppet\-strings\. -.SH "OPTIONS" -.TP -\-\-help -Print this help message -.TP -\-\-reference -Build a particular reference\. Get a list of references by running 'puppet doc \-\-list'\. -.SH "EXAMPLE" -.nf -$ puppet doc \-r type > /tmp/type_reference\.markdown -.fi -.SH "AUTHOR" -Luke Kanies -.SH "COPYRIGHT" -Copyright (c) 2011 Puppet Inc\. Copyright (c) 2024 Vox Pupuli Licensed under the Apache 2\.0 License diff --git a/spec/integration/application/doc_spec.rb b/spec/integration/application/doc_spec.rb deleted file mode 100644 index 0c35ee880c..0000000000 --- a/spec/integration/application/doc_spec.rb +++ /dev/null @@ -1,34 +0,0 @@ -require 'spec_helper' -require 'puppet/application/doc' - -describe Puppet::Application::Doc do - include PuppetSpec::Files - - let(:app) { Puppet::Application[:doc] } - - it 'lists references' do - app.command_line.args = ['-l'] - expect { - app.run - }.to exit_with(0) - .and output(/configuration - A reference for all settings/).to_stdout - end - - { - 'configuration' => /# Configuration Reference/, - 'function' => /# Function Reference/, - 'indirection' => /# Indirection Reference/, - 'metaparameter' => /# Metaparameter Reference/, - 'providers' => /# Provider Suitability Report/, - 'report' => /# Report Reference/, - 'type' => /# Type Reference/ - }.each_pair do |type, expected| - it "generates #{type} reference" do - app.command_line.args = ['-r', type] - expect { - app.run - }.to exit_with(0) - .and output(expected).to_stdout - end - end -end diff --git a/spec/unit/application/doc_spec.rb b/spec/unit/application/doc_spec.rb deleted file mode 100644 index 44f2ae7f64..0000000000 --- a/spec/unit/application/doc_spec.rb +++ /dev/null @@ -1,333 +0,0 @@ -require 'spec_helper' - -require 'puppet/application/doc' -require 'puppet/util/reference' -require 'puppet/util/rdoc' - -describe Puppet::Application::Doc do - before :each do - @doc = Puppet::Application[:doc] - allow(@doc).to receive(:puts) - @doc.preinit - allow(Puppet::Util::Log).to receive(:newdestination) - end - - it "should declare an other command" do - expect(@doc).to respond_to(:other) - end - - it "should declare a rdoc command" do - expect(@doc).to respond_to(:rdoc) - end - - it "should declare a fallback for unknown options" do - expect(@doc).to respond_to(:handle_unknown) - end - - it "should declare a preinit block" do - expect(@doc).to respond_to(:preinit) - end - - describe "in preinit" do - it "should set references to []" do - @doc.preinit - - expect(@doc.options[:references]).to eq([]) - end - - it "should init mode to text" do - @doc.preinit - - expect(@doc.options[:mode]).to eq(:text) - end - - it "should init format to to_markdown" do - @doc.preinit - - expect(@doc.options[:format]).to eq(:to_markdown) - end - end - - describe "when handling options" do - [:all, :outputdir, :verbose, :debug, :charset].each do |option| - it "should declare handle_#{option} method" do - expect(@doc).to respond_to("handle_#{option}".to_sym) - end - - it "should store argument value when calling handle_#{option}" do - expect(@doc.options).to receive(:[]=).with(option, 'arg') - @doc.send("handle_#{option}".to_sym, 'arg') - end - end - - it "should store the format if valid" do - allow(Puppet::Util::Reference).to receive(:method_defined?).with('to_format').and_return(true) - - @doc.handle_format('format') - expect(@doc.options[:format]).to eq('to_format') - end - - it "should raise an error if the format is not valid" do - allow(Puppet::Util::Reference).to receive(:method_defined?).with('to_format').and_return(false) - expect { @doc.handle_format('format') }.to raise_error(RuntimeError, /Invalid output format/) - end - - it "should store the mode if valid" do - allow(Puppet::Util::Reference).to receive(:modes).and_return(double('mode', :include? => true)) - - @doc.handle_mode('mode') - expect(@doc.options[:mode]).to eq(:mode) - end - - it "should store the mode if :rdoc" do - allow(Puppet::Util::Reference.modes).to receive(:include?).with('rdoc').and_return(false) - - @doc.handle_mode('rdoc') - expect(@doc.options[:mode]).to eq(:rdoc) - end - - it "should raise an error if the mode is not valid" do - allow(Puppet::Util::Reference.modes).to receive(:include?).with('unknown').and_return(false) - expect { @doc.handle_mode('unknown') }.to raise_error(RuntimeError, /Invalid output mode/) - end - - it "should list all references on list and exit" do - reference = double('reference') - ref = double('ref') - allow(Puppet::Util::Reference).to receive(:references).and_return([reference]) - - expect(Puppet::Util::Reference).to receive(:reference).with(reference).and_return(ref) - expect(ref).to receive(:doc) - - expect { @doc.handle_list(nil) }.to exit_with 0 - end - - it "should add reference to references list with --reference" do - @doc.options[:references] = [:ref1] - - @doc.handle_reference('ref2') - - expect(@doc.options[:references]).to eq([:ref1,:ref2]) - end - end - - describe "during setup" do - before :each do - allow(Puppet::Log).to receive(:newdestination) - allow(@doc.command_line).to receive(:args).and_return([]) - end - - it "should default to rdoc mode if there are command line arguments" do - allow(@doc.command_line).to receive(:args).and_return(["1"]) - allow(@doc).to receive(:setup_rdoc) - - @doc.setup - expect(@doc.options[:mode]).to eq(:rdoc) - end - - it "should call setup_rdoc in rdoc mode" do - @doc.options[:mode] = :rdoc - - expect(@doc).to receive(:setup_rdoc) - - @doc.setup - end - - it "should call setup_reference if not rdoc" do - @doc.options[:mode] = :test - - expect(@doc).to receive(:setup_reference) - - @doc.setup - end - - describe "configuring logging" do - before :each do - allow(Puppet::Util::Log).to receive(:newdestination) - end - - describe "with --debug" do - before do - @doc.options[:debug] = true - end - - it "should set log level to debug" do - @doc.setup - expect(Puppet::Util::Log.level).to eq(:debug) - end - - it "should set log destination to console" do - expect(Puppet::Util::Log).to receive(:newdestination).with(:console) - @doc.setup - end - end - - describe "with --verbose" do - before do - @doc.options[:verbose] = true - end - - it "should set log level to info" do - @doc.setup - expect(Puppet::Util::Log.level).to eq(:info) - end - - it "should set log destination to console" do - expect(Puppet::Util::Log).to receive(:newdestination).with(:console) - @doc.setup - end - end - - describe "without --debug or --verbose" do - before do - @doc.options[:debug] = false - @doc.options[:verbose] = false - end - - it "should set log level to warning" do - @doc.setup - expect(Puppet::Util::Log.level).to eq(:warning) - end - - it "should set log destination to console" do - expect(Puppet::Util::Log).to receive(:newdestination).with(:console) - @doc.setup - end - end - end - - describe "in non-rdoc mode" do - it "should get all non-dynamic reference if --all" do - @doc.options[:all] = true - static = double('static', :dynamic? => false) - dynamic = double('dynamic', :dynamic? => true) - allow(Puppet::Util::Reference).to receive(:reference).with(:static).and_return(static) - allow(Puppet::Util::Reference).to receive(:reference).with(:dynamic).and_return(dynamic) - allow(Puppet::Util::Reference).to receive(:references).and_return([:static,:dynamic]) - - @doc.setup_reference - expect(@doc.options[:references]).to eq([:static]) - end - - it "should default to :type if no references" do - @doc.setup_reference - expect(@doc.options[:references]).to eq([:type]) - end - end - - describe "in rdoc mode" do - describe "when there are unknown args" do - it "should expand --modulepath if any" do - @doc.unknown_args = [ { :opt => "--modulepath", :arg => "path" } ] - allow(Puppet.settings).to receive(:handlearg) - - @doc.setup_rdoc - - expect(@doc.unknown_args[0][:arg]).to eq(File.expand_path('path')) - end - - it "should give them to Puppet.settings" do - @doc.unknown_args = [ { :opt => :option, :arg => :argument } ] - expect(Puppet.settings).to receive(:handlearg).with(:option,:argument) - - @doc.setup_rdoc - end - end - - it "should operate in server run_mode" do - expect(@doc.class.run_mode.name).to eq(:server) - - @doc.setup_rdoc - end - end - end - - describe "when running" do - describe "in rdoc mode" do - include PuppetSpec::Files - - let(:envdir) { tmpdir('env') } - let(:modules) { File.join(envdir, "modules") } - let(:modules2) { File.join(envdir, "modules2") } - let(:manifests) { File.join(envdir, "manifests") } - - before :each do - @doc.manifest = false - allow(Puppet).to receive(:info) - Puppet[:trace] = false - Puppet[:modulepath] = modules - Puppet[:manifest] = manifests - @doc.options[:all] = false - @doc.options[:outputdir] = 'doc' - @doc.options[:charset] = nil - allow(Puppet.settings).to receive(:define_settings) - allow(Puppet::Util::RDoc).to receive(:rdoc) - allow(@doc.command_line).to receive(:args).and_return([]) - end - - around(:each) do |example| - FileUtils.mkdir_p(modules) - env = Puppet::Node::Environment.create(Puppet[:environment].to_sym, [modules], "#{manifests}/site.pp") - Puppet.override({:environments => Puppet::Environments::Static.new(env), :current_environment => env}) do - example.run - end - end - - it "should set document_all on --all" do - @doc.options[:all] = true - expect(Puppet.settings).to receive(:[]=).with(:document_all, true) - - expect { @doc.rdoc }.to exit_with(0) - end - - it "should call Puppet::Util::RDoc.rdoc in full mode" do - expect(Puppet::Util::RDoc).to receive(:rdoc).with('doc', [modules, manifests], nil) - expect { @doc.rdoc }.to exit_with(0) - end - - it "should call Puppet::Util::RDoc.rdoc with a charset if --charset has been provided" do - @doc.options[:charset] = 'utf-8' - expect(Puppet::Util::RDoc).to receive(:rdoc).with('doc', [modules, manifests], "utf-8") - expect { @doc.rdoc }.to exit_with(0) - end - - it "should call Puppet::Util::RDoc.rdoc in full mode with outputdir set to doc if no --outputdir" do - @doc.options[:outputdir] = false - expect(Puppet::Util::RDoc).to receive(:rdoc).with('doc', [modules, manifests], nil) - expect { @doc.rdoc }.to exit_with(0) - end - - it "should call Puppet::Util::RDoc.manifestdoc in manifest mode" do - @doc.manifest = true - expect(Puppet::Util::RDoc).to receive(:manifestdoc) - expect { @doc.rdoc }.to exit_with(0) - end - - it "should get modulepath and manifest values from the environment" do - FileUtils.mkdir_p(modules) - FileUtils.mkdir_p(modules2) - env = Puppet::Node::Environment.create(Puppet[:environment].to_sym, - [modules, modules2], - "envmanifests/site.pp") - Puppet.override({:environments => Puppet::Environments::Static.new(env), :current_environment => env}) do - allow(Puppet::Util::RDoc).to receive(:rdoc).with('doc', [modules.to_s, modules2.to_s, env.manifest.to_s], nil) - expect { @doc.rdoc }.to exit_with(0) - end - end - end - - describe "in the other modes" do - it "should get reference in given format" do - reference = double('reference') - @doc.options[:mode] = :none - @doc.options[:references] = [:ref] - expect(Puppet::Util::Reference).to receive(:reference).with(:ref).and_return(reference) - @doc.options[:format] = :format - allow(@doc).to receive(:exit) - - expect(reference).to receive(:send).with(:format, anything).and_return('doc') - @doc.other - end - end - end -end