puppet-strings 0.4.0 → 0.99.0

data/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/box_info.erb

@@ -0,0 +1,10 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/header.erb

@@ -0,0 +1 @@
+<h1>Defined Type: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/setup.rb

@@ -0,0 +1,5 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :overview, T('tags'), :source
+end

data/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/source.erb

@@ -0,0 +1,12 @@
+<div class="method_details_list">
+  <table class="source_code">
+    <tr>
+      <td>
+        <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+      </td>
+      <td>
+        <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+      </td>
+    </tr>
+  </table>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_function/html/box_info.erb

@@ -0,0 +1,14 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+  <dl>
+    <dt>Function type:</dt>
+    <dd><%= object.function_type %></dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_function/html/header.erb

@@ -0,0 +1 @@
+<h1>Puppet Function: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_function/html/overview.erb

@@ -0,0 +1,18 @@
+<h2>Overview</h2>
+<div class="method_details first">
+  <% unless object.has_tag? :overload %>
+  <div class="tags overload overload_item">
+    <span class="overload">
+      <span class="overload_item">
+        <span class="signature first" style="margin-left: 0px;"><%= "<strong>#{h(object.signature)}</strong> &#x21d2; #{signature_types(object, false)}" %></span>
+      </span>
+    </span>
+  </div>
+  <% end %>
+  <div class="docstring">
+    <div class="discussion">
+      <%= htmlify(object.docstring) %>
+    </div>
+  </div>
+  <%= yieldall %>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_function/html/setup.rb

@@ -0,0 +1,5 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :overview, [T('tags'), :source]
+end

data/lib/puppet-strings/yard/templates/default/puppet_function/html/source.erb

@@ -0,0 +1,12 @@
+<div class="method_details_list">
+  <table class="source_code">
+    <tr>
+      <td>
+        <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+      </td>
+      <td>
+        <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+      </td>
+    </tr>
+  </table>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_provider/html/box_info.erb

@@ -0,0 +1,14 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+  <dl>
+    <dt>Resource type:</dt>
+    <dd><%= linkify(Registry["puppet_types::#{object.type_name}"], object.type_name) %></dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_provider/html/collection.erb

@@ -0,0 +1,10 @@
+<% if @collection && !@collection.empty? %>
+<div class="tags">
+  <p class="tag_title"><%= @title %></p>
+  <ul>
+  <% @collection.each do |key, value| %>
+    <li><tt><%= key %> &mdash; <%= value %></tt></li>
+  <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_provider/html/features.erb

@@ -0,0 +1,12 @@
+<% if object.features && !object.features.empty? %>
+<div class="tags">
+  <p class="tag_title">Features</p>
+  <ul>
+    <% object.features.each do |feature| %>
+    <li>
+      <span class="name"><%= feature %></span>
+    </li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_provider/html/header.erb

@@ -0,0 +1 @@
+<h1>Provider: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_provider/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_provider/html/setup.rb

@@ -0,0 +1,29 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :overview, T('tags'), :features, :confines, :defaults, :commands
+end
+
+# Renders the confines section.
+# @return [String] Returns the rendered section.
+def confines
+  @title = 'Confines'
+  @collection = object.confines
+  erb(:collection)
+end
+
+# Renders the defaults section.
+# @return [String] Returns the rendered section.
+def defaults
+  @title = 'Default Provider For'
+  @collection = object.defaults
+  erb(:collection)
+end
+
+# Renders the commands section.
+# @return [String] Returns the rendered section.
+def commands
+  @title = 'Commands'
+  @collection = object.commands
+  erb(:collection)
+end

data/lib/puppet-strings/yard/templates/default/puppet_type/html/box_info.erb

@@ -0,0 +1,20 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+  <% if @providers && !@providers.empty? %>
+  <dl>
+    <dt>Providers:</dt>
+    <dd>
+      <% @providers.each do |provider| %>
+        <%= linkify(provider, provider.name.to_s) %><br/>
+      <% end %>
+    </dd>
+  </dl>
+  <% end %>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_type/html/features.erb

@@ -0,0 +1,13 @@
+<% if object.features && !object.features.empty? %>
+<div class="tags">
+  <p class="tag_title">Features</p>
+  <ul>
+    <% object.features.each do |feature| %>
+    <li>
+      <span class="name"><%= feature.name %></span>
+      <% unless feature.docstring.empty? %> &mdash; <%= htmlify_line(feature.docstring) %><% end %>
+    </li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_type/html/header.erb

@@ -0,0 +1 @@
+<h1>Resource Type: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_type/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_type/html/parameters.erb

@@ -0,0 +1,35 @@
+<% if @parameters && !@parameters.empty? %>
+<div class="tags">
+  <p class="tag_title"><%= @tag_title %></p>
+  <ul>
+    <% @parameters.each do |parameter| %>
+    <li>
+      <span class="name"><%= parameter.name + (parameter.isnamevar ? ' (namevar)' : '') %></span>
+      <% if parameter.default %>
+      <span class="default"> (defaults to: <em><%= parameter.default %></em>)</span>
+      <% end %>
+      <% unless parameter.docstring.empty? %>
+      <div class="docstring">
+        <div class="discussion">
+          <%= htmlify(parameter.docstring) %>
+        </div>
+      </div>
+      <% end %>
+      <% unless parameter.values.empty? %>
+      <div>
+        Supported values:
+        <ul>
+          <% parameter.values.each do |value| %>
+          <li>
+            <% other = parameter.aliases[value] %>
+            <%= value %><% if other %> (alias for: <em><%= other %></em>)<% end %>
+          </li>
+          <% end %>
+        </ul>
+      </div>
+      <% end %>
+    </li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb

@@ -0,0 +1,32 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :overview, T('tags'), :properties, :parameters, :features
+end
+
+# Renders the box_info section.
+# @return [String] Returns the rendered section.
+def box_info
+  @providers = PuppetStrings::Yard::CodeObjects::Providers.instance(object.name).children
+  erb(:box_info)
+end
+
+# Renders the properties section.
+# @return [String] Returns the rendered section.
+def properties
+  # Properties are the same thing as parameters (from the documentation standpoint),
+  # so reuse the same template but with a different title and data source.
+  @parameters = object.properties || []
+  @parameters.sort_by! { |p| p.name }
+  @tag_title = 'Properties'
+  erb(:parameters)
+end
+
+# Renders the parameters section.
+# @return [String] Returns the rendered section.
+def parameters
+  @parameters = object.parameters || []
+  @parameters.sort_by! { |p| p.name }
+  @tag_title = 'Parameters'
+  erb(:parameters)
+end

data/lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb

@@ -0,0 +1,12 @@
+<% if object.has_tag?(:overload) && object.tags(:overload).any? {|o| !o.docstring.blank? } %>
+  <p class="tag_title">Overloads:</p>
+  <ul class="overload">
+    <% object.tags(:overload).each_with_index do |overload, index| %>
+      <% next if overload.docstring.blank? %>
+      <li class="overload_item">
+        <span class="signature"><%= "<strong>#{h(overload.signature)}</strong> &#x21d2; #{signature_types(overload, false)}" %></span>
+        <%= yieldall :object => overload %>
+      </li>
+    <% end %>
+  </ul>
+<% end %>

data/lib/puppet-strings/yard/templates/default/tags/setup.rb

@@ -0,0 +1,15 @@
+# Called to return parameter tags.
+# @return [Array<YARD::Tag>] Returns the parameter tags if the object should have parameters.
+def param
+  tag(:param) if
+    object.type == :method ||
+    object.type == :puppet_class ||
+    object.type == :puppet_defined_type ||
+    object.type == :puppet_function
+end
+
+# Renders the overload section.
+# @return [String] Returns the rendered section.
+def overload
+  erb(if object.type == :puppet_function then :puppet_overload else :overload end)
+end

data/lib/puppet/application/strings.rb

@@ -1,4 +1,5 @@
 require 'puppet/application/face_base'
 
+# Implements the 'puppet strings' application.
 class Puppet::Application::Strings < Puppet::Application::FaceBase
 end

data/lib/puppet/face/strings.rb

@@ -1,64 +1,105 @@
 require 'puppet/face'
-require 'puppet_x/puppetlabs/strings/yard/tags/directives'
 
+# Implements the 'puppet strings' interface.
 Puppet::Face.define(:strings, '0.0.1') do
-  summary "Generate Puppet documentation with YARD."
+  summary 'Generate Puppet documentation with YARD.'
 
-  # Ensures that the user has the needed features to use puppet strings
-  def check_required_features
-    unless Puppet.features.yard?
-      raise RuntimeError, "The 'yard' gem must be installed in order to use this face."
-    end
+  action(:generate) do
+    default
 
-    unless Puppet.features.rgen?
-      raise RuntimeError, "The 'rgen' gem must be installed in order to use this face."
+    option '--emit-json-stdout' do
+      summary 'Print JSON representation of the documentation to stdout.'
     end
-
-    if RUBY_VERSION.match(/^1\.8/)
-      raise RuntimeError, "This face requires Ruby 1.9 or greater."
+    option '--emit-json FILE' do
+      summary 'Write JSON representation of the documentation to the given file.'
+    end
+    option '--markup FORMAT' do
+      summary "The markup format to use for docstring text (defaults to 'markdown')."
     end
-  end
 
-  action(:yardoc) do
-    default
+    summary 'Generate documentation from files.'
+    arguments '[[search_pattern] ...]'
 
-    option "--emit-json-stdout" do
-      summary "Print json representation of the documentation to stdout"
+    when_invoked do |*args|
+      check_required_features
+      require 'puppet-strings'
+
+      PuppetStrings::generate(
+        args.count > 1 ? args[0..-2] : PuppetStrings::DEFAULT_SEARCH_PATTERNS,
+        build_generate_options(args.last)
+      )
+      nil
     end
-    option "--emit-json FILE" do
-      summary "Write json representation of the documentation to FILE"
+  end
+
+  action(:server) do
+    option '--markup FORMAT' do
+      summary "The markup format to use for docstring text (defaults to 'markdown')."
     end
 
-    summary "Generate YARD documentation from files."
-    arguments "[manifest_file.pp ...]"
+    summary 'Runs a local documentation server for the modules in the current Puppet environment.'
+    arguments '[[module_name] ...]'
 
     when_invoked do |*args|
       check_required_features
-      require 'puppet_x/puppetlabs/strings/util'
+      require 'puppet-strings'
+
+      modules = args.count > 1 ? args[0..-2] : []
 
-      PuppetX::PuppetLabs::Strings::Util.generate(args)
+      # Generate documentation for all (or the given) modules
+      module_docs = []
+      environment = Puppet.lookup(:current_environment)
+      environment.modules.each do |mod|
+        next unless modules.empty? || modules.include?(mod.name)
+        db = File.join(mod.path, '.yardoc')
+        patterns = PuppetStrings::DEFAULT_SEARCH_PATTERNS.map do |p|
+          File.join(mod.path, p)
+        end
+        puts "Generating documentation for Puppet module '#{mod.name}'."
+        PuppetStrings.generate(patterns, build_generate_options(args.last, '--db', db))
 
-      # Puppet prints the return value of the action. The return value of this
-      # action is that of the yardoc_actions invocation, which is the boolean
-      # "true". This clutters the statistics yard prints, so instead return the
-      # empty string. Note an extra newline will also be printed.
-      ""
+        # Clear the registry so that the next call to generate has a clean database
+        YARD::Registry.clear
+
+        module_docs << mod.name
+        module_docs << db
+      end
+
+      if module_docs.empty?
+        puts 'No Puppet modules were found to serve documentation for.'
+        return
+      end
+      puts 'Starting YARD documentation server.'
+      PuppetStrings::run_server('-m', *module_docs)
+      nil
     end
   end
 
-  # NOTE: Modeled after the `yard gems` command which builds doc indicies
-  # (.yardoc directories) for Ruby Gems. Currently lacks the fine-grained
-  # control over where these indicies are created and just dumps them in the
-  # module roots.
-
-  action(:server) do
-    summary "Serve YARD documentation for modules."
+  # Checks that the required features are installed.
+  # @return [void]
+  def check_required_features
+    raise RuntimeError, "The 'yard' gem must be installed in order to use this face." unless Puppet.features.yard?
+    raise RuntimeError, "The 'rgen' gem must be installed in order to use this face." unless Puppet.features.rgen?
+    raise RuntimeError, 'This face requires Ruby 1.9 or greater.' if RUBY_VERSION =~ /^1\.8/
+  end
 
-    when_invoked do |*args|
-      check_required_features
-      require 'puppet_x/puppetlabs/strings/util'
+  # Builds the options to PuppetStrings.generate.
+  # @param [Hash] options The Puppet face options hash.
+  # @param [Array] yard_args The additional arguments to pass to YARD.
+  # @return [Hash] Returns the PuppetStrings.generate options hash.
+  def build_generate_options(options = nil, *yard_args)
+    generate_options = {}
+    generate_options[:debug] = Puppet[:debug]
+    generate_options[:backtrace] = Puppet[:trace]
+    generate_options[:yard_args] = yard_args unless yard_args.empty?
 
-      PuppetX::PuppetLabs::Strings::Util.serve(args)
+    if options
+      markup = options[:markup]
+      generate_options[:markup] = markup if markup
+      json_file = options[:emit_json]
+      generate_options[:json] = json_file if json_file
+      generate_options[:json] = nil if options[:emit_json_stdout]
     end
+    generate_options
   end
 end