From 7c06ed77c4825f35e6ac8b2ca69da690671ef7e2 Mon Sep 17 00:00:00 2001 From: Eric Putnam Date: Wed, 7 Feb 2018 15:12:47 -0800 Subject: [PATCH] (PDOC-184) block pointless output and re-add options This makes sure the markdown doesn't include section headers that have no content. e.g. '## Classes' does not get put in if there are no classes. Also, we should deprecate --emit-json and --emit-json-stdout instead of just killing them. --- lib/puppet-strings.rb | 5 +++-- lib/puppet-strings/markdown/puppet_classes.rb | 4 +++- .../markdown/puppet_defined_types.rb | 4 +++- lib/puppet-strings/markdown/puppet_functions.rb | 4 +++- .../markdown/puppet_resource_types.rb | 4 +++- .../markdown/templates/table_of_contents.erb | 8 ++++---- lib/puppet/face/strings.rb | 16 ++++++++++++++-- 7 files changed, 33 insertions(+), 12 deletions(-) diff --git a/lib/puppet-strings.rb b/lib/puppet-strings.rb index 1e1254d..75567f9 100644 --- a/lib/puppet-strings.rb +++ b/lib/puppet-strings.rb @@ -29,6 +29,7 @@ module PuppetStrings args << '--backtrace' if options[:backtrace] args << "-m#{options[:markup] || 'markdown'}" + file = nil if options[:json] || options[:markdown] file = options[:path] # Disable output and prevent stats/progress when writing to STDOUT @@ -47,12 +48,12 @@ module PuppetStrings # If outputting JSON, render the output if options[:json] - render_json(options[:path]) + render_json(file) end # If outputting Markdown, render the output if options[:markdown] - render_markdown(options[:path]) + render_markdown(file) end end diff --git a/lib/puppet-strings/markdown/puppet_classes.rb b/lib/puppet-strings/markdown/puppet_classes.rb index 83237d8..0818f9f 100644 --- a/lib/puppet-strings/markdown/puppet_classes.rb +++ b/lib/puppet-strings/markdown/puppet_classes.rb @@ -2,12 +2,14 @@ require_relative 'puppet_class' module PuppetStrings::Markdown module PuppetClasses + + # @return [Array] list of classes def self.in_classes YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash) end def self.render - final = "## Classes\n\n" + final = in_classes.length > 0 ? "## Classes\n\n" : "" in_classes.each do |klass| final << PuppetStrings::Markdown::PuppetClass.new(klass).render end diff --git a/lib/puppet-strings/markdown/puppet_defined_types.rb b/lib/puppet-strings/markdown/puppet_defined_types.rb index 7936871..838fb45 100644 --- a/lib/puppet-strings/markdown/puppet_defined_types.rb +++ b/lib/puppet-strings/markdown/puppet_defined_types.rb @@ -2,12 +2,14 @@ require_relative 'puppet_defined_type' module PuppetStrings::Markdown module PuppetDefinedTypes + + # @return [Array] list of defined types def self.in_dtypes YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash) end def self.render - final = "## Defined types\n\n" + final = in_dtypes.length > 0 ? "## Defined types\n\n" : "" in_dtypes.each do |type| final << PuppetStrings::Markdown::PuppetDefinedType.new(type).render end diff --git a/lib/puppet-strings/markdown/puppet_functions.rb b/lib/puppet-strings/markdown/puppet_functions.rb index 4f0dbd3..5b0e177 100644 --- a/lib/puppet-strings/markdown/puppet_functions.rb +++ b/lib/puppet-strings/markdown/puppet_functions.rb @@ -2,12 +2,14 @@ require_relative 'puppet_function' module PuppetStrings::Markdown module PuppetFunctions + + # @return [Array] list of functions def self.in_functions YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash) end def self.render - final = "## Functions\n\n" + final = in_functions.length > 0 ? "## Functions\n\n" : "" in_functions.each do |func| final << PuppetStrings::Markdown::PuppetFunction.new(func).render end diff --git a/lib/puppet-strings/markdown/puppet_resource_types.rb b/lib/puppet-strings/markdown/puppet_resource_types.rb index faee0cb..e67690e 100644 --- a/lib/puppet-strings/markdown/puppet_resource_types.rb +++ b/lib/puppet-strings/markdown/puppet_resource_types.rb @@ -2,12 +2,14 @@ require_relative 'puppet_resource_type' module PuppetStrings::Markdown module PuppetResourceTypes + + # @return [Array] list of resource types def self.in_rtypes YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash) end def self.render - final = "## Resource types\n\n" + final = in_rtypes.length > 0 ? "## Resource types\n\n" : "" in_rtypes.each do |type| final << PuppetStrings::Markdown::PuppetResourceType.new(type).render end diff --git a/lib/puppet-strings/markdown/templates/table_of_contents.erb b/lib/puppet-strings/markdown/templates/table_of_contents.erb index ecf0735..d726b5e 100644 --- a/lib/puppet-strings/markdown/templates/table_of_contents.erb +++ b/lib/puppet-strings/markdown/templates/table_of_contents.erb @@ -1,22 +1,22 @@ -<% if puppet_classes -%> +<% if puppet_classes.length > 0 -%> ## Classes <% puppet_classes.each do |klassy| -%> * [`<%= klassy[:name] %>`](#<%= klassy[:link] %>): <%= klassy[:desc] %> <% end -%> <% end -%> -<% if puppet_defined_types -%> +<% if puppet_defined_types.length > 0 -%> ## Defined types <% puppet_defined_types.each do |dtype| -%> * [`<%= dtype[:name] %>`](#<%= dtype[:link] %>): <%= dtype[:desc] %> <% end -%> <% end -%> -<% if puppet_resource_types -%> +<% if puppet_resource_types.length > 0 -%> ## Resource types <% puppet_resource_types.each do |rtype| -%> * [`<%= rtype[:name] %>`](#<%= rtype[:link] %>): <%= rtype[:desc] %> <% end -%> <% end -%> -<% if puppet_functions -%> +<% if puppet_functions.length > 0 -%> ## Functions <% puppet_functions.each do |func| -%> * [`<%= func[:name] %>`](#<%= func[:link] %>): <%= func[:desc] %> diff --git a/lib/puppet/face/strings.rb b/lib/puppet/face/strings.rb index 5b5f0a3..d86e895 100644 --- a/lib/puppet/face/strings.rb +++ b/lib/puppet/face/strings.rb @@ -16,6 +16,12 @@ Puppet::Face.define(:strings, '0.0.1') do option '--markup FORMAT' do summary "The markup format to use for docstring text (defaults to 'markdown')." end + option '--emit-json-stdout' do + summary 'DEPRECATED: Print JSON representation of the documentation to stdout.' + end + option '--emit-json PATH' do + summary 'DEPRECATED: Write JSON representation of the documentation to the given file.' + end summary 'Generate documentation from files.' arguments '[[search_pattern] ...]' @@ -94,14 +100,20 @@ Puppet::Face.define(:strings, '0.0.1') do generate_options[:yard_args] = yard_args unless yard_args.empty? if options + if options[:emit_json] + $stderr.puts "WARNING: '--emit-json PATH' is deprecated. Use '--format json --out PATH' instead." + end + if options[:emit_json_stdout] + $stderr.puts "WARNING: '--emit-json-stdout' is deprecated. Use '--format json' instead." + end markup = options[:markup] generate_options[:markup] = markup if markup generate_options[:path] = options[:out] if options[:out] generate_options[:stdout] = options[:stdout] format = options[:format] || "" - if format.casecmp 'markdown' + if format.casecmp('markdown') == 0 generate_options[:markdown] = true - elsif format.casecmp 'json' + elsif format.casecmp('json') == 0 || options[:emit_json] || options[:emit_json_stdout] generate_options[:json] = true end end