From 59e7ef15507de48f6504ef21a8e0e775104961c6 Mon Sep 17 00:00:00 2001 From: Daniel Pittman Date: Tue, 26 Apr 2011 23:30:08 -0700 Subject: (#6962) Move documentation support into a module. Given that we have identical documentation behaviour in the face and action code, it should properly be written once. So, move it into a module, extend the other classes with it, and have done. --- lib/puppet/interface/action.rb | 52 ++++++---- lib/puppet/interface/action_manager.rb | 4 +- lib/puppet/interface/documentation.rb | 168 +++++++++++++++++++++++++++++++++ 3 files changed, 207 insertions(+), 17 deletions(-) create mode 100644 lib/puppet/interface/documentation.rb (limited to 'lib/puppet/interface') diff --git a/lib/puppet/interface/action.rb b/lib/puppet/interface/action.rb index 08bc0a345..18c7ab057 100644 --- a/lib/puppet/interface/action.rb +++ b/lib/puppet/interface/action.rb @@ -1,12 +1,21 @@ -# -*- coding: utf-8 -*- require 'puppet/interface' -require 'puppet/interface/option' +require 'puppet/interface/documentation' +require 'prettyprint' class Puppet::Interface::Action + include Puppet::Interface::DocSupport + def initialize(face, name, attrs = {}) raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/ @face = face @name = name.to_sym + + # The few bits of documentation we actually demand. The default license + # is a favour to our end users; if you happen to get that in a core face + # report it as a bug, please. --daniel 2011-04-26 + @authors = [] + @license = 'All Rights Reserved' + attrs.each do |k, v| send("#{k}=", v) end @options = {} @@ -30,8 +39,31 @@ class Puppet::Interface::Action !!@default end - attr_accessor :summary - + ######################################################################## + # Documentation... + def synopsis + output = PrettyPrint.format do |s| + s.text("puppet #{@face.name}") + s.text(" #{name}") unless default? + s.breakable + + options.each do |option| + option = get_option(option) + wrap = option.required? ? %w{ < > } : %w{ [ ] } + + s.group(0, *wrap) do + option.optparse.each do |item| + unless s.current_group.first? + s.breakable + s.text '|' + s.breakable + end + s.text item + end + end + end + end + end ######################################################################## # Support for rendering formats and all. @@ -82,18 +114,6 @@ class Puppet::Interface::Action end - ######################################################################## - # Documentation stuff, whee! - attr_accessor :summary, :description - def summary=(value) - value = value.to_s - value =~ /\n/ and - raise ArgumentError, "Face summary should be a single line; put the long text in 'description' instead." - - @summary = value - end - - ######################################################################## # Initially, this was defined to allow the @action.invoke pattern, which is # a very natural way to invoke behaviour given our introspection diff --git a/lib/puppet/interface/action_manager.rb b/lib/puppet/interface/action_manager.rb index 440be2d1b..c5eb8e08a 100644 --- a/lib/puppet/interface/action_manager.rb +++ b/lib/puppet/interface/action_manager.rb @@ -1,9 +1,11 @@ -require 'puppet/interface/action_builder' +require 'puppet/interface/action' module Puppet::Interface::ActionManager # Declare that this app can take a specific action, and provide # the code to do so. def action(name, &block) + require 'puppet/interface/action_builder' + @actions ||= {} @default_action ||= nil raise "Action #{name} already defined for #{self}" if action?(name) diff --git a/lib/puppet/interface/documentation.rb b/lib/puppet/interface/documentation.rb new file mode 100644 index 000000000..f3bf33da5 --- /dev/null +++ b/lib/puppet/interface/documentation.rb @@ -0,0 +1,168 @@ +class Puppet::Interface + module DocSupport + attr_accessor :summary + def summary(value = nil) + self.summary = value unless value.nil? + @summary + end + def summary=(value) + value = value.to_s + value =~ /\n/ and + raise ArgumentError, "Face summary should be a single line; put the long text in 'description' instead." + + @summary = value + end + + attr_accessor :description + def description(value = nil) + self.description = value unless value.nil? + @description + end + + attr_accessor :examples + def examples(value = nil) + self.examples = value unless value.nil? + @examples + end + + attr_accessor :short_description + def short_description(value = nil) + self.short_description = value unless value.nil? + if @short_description.nil? then + return nil if @description.nil? + lines = @description.split("\n") + grab = [5, lines.index('') || 5].min + @short_description = lines[0, grab].join("\n") + end + @short_description + end + + def author(value = nil) + unless value.nil? then + unless value.is_a? String + raise ArgumentError, 'author must be a string; use multiple statements for multiple authors' + end + + if value =~ /\n/ then + raise ArgumentError, 'author should be a single line; use multiple statements for multiple authors' + end + @authors.push(value) + end + @authors.empty? ? nil : @authors.join("\n") + end + def author=(value) + if Array(value).any? {|x| x =~ /\n/ } then + raise ArgumentError, 'author should be a single line; use multiple statements' + end + @authors = Array(value) + end + def authors + @authors + end + def authors=(value) + if Array(value).any? {|x| x =~ /\n/ } then + raise ArgumentError, 'author should be a single line; use multiple statements' + end + @authors = Array(value) + end + + attr_accessor :notes + def notes(value = nil) + @notes = value unless value.nil? + @notes + end + + attr_accessor :license + def license(value = nil) + @license = value unless value.nil? + @license + end + + def copyright(owner = nil, years = nil) + if years.nil? and not owner.nil? then + raise ArgumentError, 'copyright takes the owners names, then the years covered' + end + self.copyright_owner = owner unless owner.nil? + self.copyright_years = years unless years.nil? + + if self.copyright_years or self.copyright_owner then + "Copyright #{self.copyright_years} by #{self.copyright_owner}" + else + "Unknown copyright owner and years." + end + end + + attr_accessor :copyright_owner + def copyright_owner=(value) + case value + when String then @copyright_owner = value + when Array then @copyright_owner = value.join(", ") + else + raise ArgumentError, "copyright owner must be a string or an array of strings" + end + @copyright_owner + end + + attr_accessor :copyright_years + def copyright_years=(value) + years = munge_copyright_year value + years = (years.is_a?(Array) ? years : [years]). + sort_by do |x| x.is_a?(Range) ? x.first : x end + + @copyright_years = years.map do |year| + if year.is_a? Range then + "#{year.first}-#{year.last}" + else + year + end + end.join(", ") + end + + def munge_copyright_year(input) + case input + when Range then input + when Integer then + if input < 1970 then + fault = "before 1970" + elsif input > (future = Time.now.year + 2) then + fault = "after #{future}" + end + if fault then + raise ArgumentError, "copyright with a year #{fault} is very strange; did you accidentally add or subtract two years?" + end + + input + + when String then + input.strip.split(/,/).map do |part| + part = part.strip + if part =~ /^\d+$/ then + part.to_i + elsif found = part.split(/-/) then + unless found.length == 2 and found.all? {|x| x.strip =~ /^\d+$/ } + raise ArgumentError, "#{part.inspect} is not a good copyright year or range" + end + Range.new(found[0].to_i, found[1].to_i) + else + raise ArgumentError, "#{part.inspect} is not a good copyright year or range" + end + end + + when Array then + result = [] + input.each do |item| + item = munge_copyright_year item + if item.is_a? Array + result.concat item + else + result << item + end + end + result + + else + raise ArgumentError, "#{input.inspect} is not a good copyright year, set, or range" + end + end + end +end -- cgit From e8eb290a1681baa19ef0b035af7cf17daadc6069 Mon Sep 17 00:00:00 2001 From: Daniel Pittman Date: Wed, 27 Apr 2011 10:05:48 -0700 Subject: (#6962) Finish documentation API on Face options. This extends the last of the documentation support, down into options, so they can be described as expected. In the process we split out the modular docs API into a full and short version options only want short docs, but the behaviours are identical to the full version. --- lib/puppet/interface/action.rb | 2 +- lib/puppet/interface/documentation.rb | 6 +++++- lib/puppet/interface/option.rb | 6 +++++- 3 files changed, 11 insertions(+), 3 deletions(-) (limited to 'lib/puppet/interface') diff --git a/lib/puppet/interface/action.rb b/lib/puppet/interface/action.rb index 18c7ab057..177df81f2 100644 --- a/lib/puppet/interface/action.rb +++ b/lib/puppet/interface/action.rb @@ -3,7 +3,7 @@ require 'puppet/interface/documentation' require 'prettyprint' class Puppet::Interface::Action - include Puppet::Interface::DocSupport + include Puppet::Interface::FullDocs def initialize(face, name, attrs = {}) raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/ diff --git a/lib/puppet/interface/documentation.rb b/lib/puppet/interface/documentation.rb index f3bf33da5..d0bfbb261 100644 --- a/lib/puppet/interface/documentation.rb +++ b/lib/puppet/interface/documentation.rb @@ -1,5 +1,5 @@ class Puppet::Interface - module DocSupport + module TinyDocs attr_accessor :summary def summary(value = nil) self.summary = value unless value.nil? @@ -18,6 +18,10 @@ class Puppet::Interface self.description = value unless value.nil? @description end + end + + module FullDocs + include TinyDocs attr_accessor :examples def examples(value = nil) diff --git a/lib/puppet/interface/option.rb b/lib/puppet/interface/option.rb index 3d3840ff6..493b5c3bd 100644 --- a/lib/puppet/interface/option.rb +++ b/lib/puppet/interface/option.rb @@ -1,6 +1,10 @@ require 'puppet/interface' class Puppet::Interface::Option + include Puppet::Interface::FullDocs + # For compatibility, deprecated, and should go fairly soon... + ['', '='].each { |x| alias :"desc#{x}" :"description#{x}" } + def initialize(parent, *declaration, &block) @parent = parent @optparse = [] @@ -80,7 +84,7 @@ class Puppet::Interface::Option end attr_reader :parent, :name, :aliases, :optparse - attr_accessor :required, :desc + attr_accessor :required attr_accessor :before_action def before_action=(proc) -- cgit From 0256d67e1a51a37f2c87ec197bdff6ef3a6b269f Mon Sep 17 00:00:00 2001 From: Daniel Pittman Date: Wed, 27 Apr 2011 10:38:41 -0700 Subject: (#6962) Add integration tests on Face documentation. We now run all the faces, and their actions, as well as global help through the wringer in this test: this way we can be confident that we have, at least, the ability to generate the help without a user-visible failure. We also check that we have set copyright and license terms in our own faces. Theoretically this might fail if the end user has extra faces on LOAD_PATH, but my hope is that we won't hit that... --- lib/puppet/interface/option.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/puppet/interface') diff --git a/lib/puppet/interface/option.rb b/lib/puppet/interface/option.rb index 493b5c3bd..b68bdeb12 100644 --- a/lib/puppet/interface/option.rb +++ b/lib/puppet/interface/option.rb @@ -1,7 +1,7 @@ require 'puppet/interface' class Puppet::Interface::Option - include Puppet::Interface::FullDocs + include Puppet::Interface::TinyDocs # For compatibility, deprecated, and should go fairly soon... ['', '='].each { |x| alias :"desc#{x}" :"description#{x}" } -- cgit