Merge pull request #4 from hkenney/PDOC-3_refactor-prototype-code

(PDOC-3) Rename face to strings instead of yardoc
This commit is contained in:
Andrew Parker 2014-09-17 10:32:31 -07:00
commit 6fb4a39536
44 changed files with 120 additions and 117 deletions

View File

@ -1,4 +1,4 @@
Puppet YARDoc
Puppet Strings
=============
A Puppet Face and plugin built on the [YARD Documentation Tool](http://yardoc.org/) and Puppet Future Parser.
@ -23,13 +23,13 @@ Usage
Documenting a module:
cd /path/to/module
puppet yardoc
puppet strings
This processes `README` and everything in `manifests/**/*.pp`.
Documenting specific manifests:
puppet yardoc some_manifest.pp [another_if_you_feel_like_it.pp]
puppet strings some_manifest.pp [another_if_you_feel_like_it.pp]
Processing is delegated to the `yardoc` tool so some options listed in `yard help doc` are available.
However, Puppet Faces do not support passing arbitrary options through a face so these options must be specified in a `.yardopts` file.

View File

@ -0,0 +1,4 @@
require 'puppet/application/face_base'
class Puppet::Application::Strings < Puppet::Application::FaceBase
end

View File

@ -1,4 +0,0 @@
require 'puppet/application/face_base'
class Puppet::Application::Yardoc < Puppet::Application::FaceBase
end

View File

@ -1,6 +1,6 @@
require 'puppet/face'
Puppet::Face.define(:yardoc, '0.0.1') do
Puppet::Face.define(:strings, '0.0.1') do
summary "Generate Puppet documentation with YARD."
def check_required_features
@ -54,7 +54,7 @@ Puppet::Face.define(:yardoc, '0.0.1') do
yard_args = (args.empty? ? MODULE_SOURCEFILES : args)
merge_puppet_args!(yard_args)
require 'puppetx/yardoc/yard/plugin'
require 'puppetx/puppetlabs/strings/yard/plugin'
# Hand off to YARD for further processing.
YARD::CLI::Yardoc.run(*yard_args)
@ -71,7 +71,7 @@ Puppet::Face.define(:yardoc, '0.0.1') do
when_invoked do |*args|
check_required_features
require 'puppetx/yardoc/yard/plugin'
require 'puppetx/puppetlabs/strings/yard/plugin'
opts = args.pop
# NOTE: The retrun value of the `module` Face seems to have changed in
@ -105,13 +105,13 @@ Puppet::Face.define(:yardoc, '0.0.1') do
when_invoked do |*args|
check_required_features
require 'puppetx/yardoc/yard/plugin'
require 'puppetx/puppetlabs/strings/yard/plugin'
opts = args.pop
# FIXME: This is pretty inefficient as it forcibly re-generates the YARD
# indicies each time the server is started. However, it ensures things are
# generated properly.
module_list = Puppet::Face[:yardoc, :current].modules
module_list = Puppet::Face[:strings, :current].modules
module_tuples = module_list.map do |mod|
name = (mod.forge_name || mod.name).gsub('/', '-')

View File

@ -0,0 +1,16 @@
require 'puppetx'
# Nothing to see here except forward declarations.
module Puppetx::PuppetLabs
module Strings
# This submodule contains bits that interface with the YARD plugin system.
module YARD
end
# This submodule contains bits that operate on the Pops module produced by
# the Future parser.
module Pops
end
end
end

View File

@ -1,9 +1,9 @@
require 'ostruct'
require 'puppet/pops'
require_relative '../../yardoc'
require_relative '../../strings'
module Puppetx::Yardoc::Pops
module Puppetx::PuppetLabs::Strings::Pops
# An adapter class that conforms a Pops model instance + adapters to the
# interface expected by YARD handlers.
#

View File

@ -1,9 +1,9 @@
require 'puppet/pops'
require_relative '../../yardoc'
require_relative '../../strings'
require_relative 'yard_statement'
module Puppetx::Yardoc::Pops
module Puppetx::PuppetLabs::Strings::Pops
# Loosely based on the TreeDumper classes in Pops::Model. The responsibility of
# this class is to walk a Pops::Model and output objects that can be consumed
# by YARD handlers.

View File

@ -2,7 +2,7 @@ require 'puppet/pops'
require_relative 'puppet_namespace_object'
module Puppetx::Yardoc::YARD::CodeObjects
module Puppetx::PuppetLabs::Strings::YARD::CodeObjects
class DefinedTypeObject < PuppetNamespaceObject
# A list of parameters attached to this class.
# @return [Array<Array(String, String)>]

View File

@ -1,6 +1,6 @@
require_relative 'defined_type_object'
module Puppetx::Yardoc::YARD::CodeObjects
module Puppetx::PuppetLabs::Strings::YARD::CodeObjects
class HostClassObject < DefinedTypeObject
# The {HostClassObject} that this class inherits from, if any.
# @return [HostClassObject, Proxy, nil]

View File

@ -1,8 +1,8 @@
require 'yard'
require_relative '../../../yardoc'
require_relative '../../../strings'
module Puppetx::Yardoc::YARD::CodeObjects
module Puppetx::PuppetLabs::Strings::YARD::CodeObjects
class PuppetNamespaceObject < YARD::CodeObjects::NamespaceObject
# NOTE: `YARD::Registry#resolve` requires a method with this signature to
# be present on all subclasses of `NamespaceObject`.

View File

@ -2,5 +2,5 @@ require_relative 'handlers/base'
require_relative 'handlers/defined_type_handler'
require_relative 'handlers/host_class_handler'
require_relative 'handlers/parser_function_handler'
require_relative 'handlers/future_parser_function_handler'
require_relative 'handlers/puppet_3x_function_handler'
require_relative 'handlers/puppet_4x_function_handler'

View File

@ -1,15 +1,15 @@
require 'yard'
require 'puppet/pops'
require_relative '../../../yardoc'
require_relative '../../../strings'
require_relative '../code_objects'
module Puppetx::Yardoc::YARD::Handlers
module Puppetx::PuppetLabs::Strings::YARD::Handlers
class Base < YARD::Handlers::Base
# Easy access to Pops model objects for handler matching.
include Puppet::Pops::Model
# Easy access to custom code objects from which documentation is generated.
include Puppetx::Yardoc::YARD::CodeObjects
include Puppetx::PuppetLabs::Strings::YARD::CodeObjects
def self.handles?(statement)
handlers.any? {|h| h == statement.type}

View File

@ -1,6 +1,6 @@
require_relative 'base'
module Puppetx::Yardoc::YARD::Handlers
module Puppetx::PuppetLabs::Strings::YARD::Handlers
class DefinedTypeHandler < Base
handles ResourceTypeDefinition

View File

@ -1,6 +1,6 @@
require_relative 'base'
module Puppetx::Yardoc::YARD::Handlers
module Puppetx::PuppetLabs::Strings::YARD::Handlers
class HostClassHandler < Base
handles HostClassDefinition

View File

@ -3,9 +3,9 @@ require 'puppet/util/docs'
require_relative '../code_objects'
module Puppetx::Yardoc::YARD::Handlers
class ParserFunctionHandler < YARD::Handlers::Ruby::Base
include Puppetx::Yardoc::YARD::CodeObjects
module Puppetx::PuppetLabs::Strings::YARD::Handlers
class Puppet3xFunctionHandler < YARD::Handlers::Ruby::Base
include Puppetx::PuppetLabs::Strings::YARD::CodeObjects
handles method_call(:newfunction)
@ -40,11 +40,11 @@ module Puppetx::Yardoc::YARD::Handlers
# @return [PuppetNamespaceObject]
def function_namespace
# NOTE: This tricky. If there is ever a Ruby class or module with the
# name ::ParserFunctions, then there will be a clash. Hopefully the name
# name ::Puppet3xFunctions, then there will be a clash. Hopefully the name
# is sufficiently uncommon.
obj = P(:root, 'ParserFunctions')
obj = P(:root, 'Puppet3xFunctions')
if obj.is_a? Proxy
namespace_obj = PuppetNamespaceObject.new(:root, 'ParserFunctions')
namespace_obj = PuppetNamespaceObject.new(:root, 'Puppet3xFunctions')
namespace_obj.add_tag YARD::Tags::Tag.new(:api, 'public')
register namespace_obj

View File

@ -1,16 +1,16 @@
require_relative '../code_objects'
module Puppetx::Yardoc::YARD::Handlers
module Puppetx::PuppetLabs::Strings::YARD::Handlers
# Handles `dispatch` calls within a future parser function declaration. For
# now, it just treats any docstring as an `@overlaod` tag and attaches the
# overload to the parent function.
class FutureParserDispatchHandler < YARD::Handlers::Ruby::Base
include Puppetx::Yardoc::YARD::CodeObjects
class Puppet4xFunctionHandler < YARD::Handlers::Ruby::Base
include Puppetx::PuppetLabs::Strings::YARD::CodeObjects
handles method_call(:dispatch)
process do
return unless owner.is_a?(MethodObject) && owner['future_parser_function']
return unless owner.is_a?(MethodObject) && owner['puppet_4x_function']
return unless statement.docstring
docstring = ::YARD::Docstring.new(statement.docstring, nil)
@ -21,8 +21,8 @@ module Puppetx::Yardoc::YARD::Handlers
end
end
class FutureParserFunctionHandler < YARD::Handlers::Ruby::Base
include Puppetx::Yardoc::YARD::CodeObjects
class Puppet4xFunctionHandler < YARD::Handlers::Ruby::Base
include Puppetx::PuppetLabs::Strings::YARD::CodeObjects
handles method_call(:create_function)
@ -30,7 +30,7 @@ module Puppetx::Yardoc::YARD::Handlers
name = process_parameters
obj = MethodObject.new(function_namespace, name)
obj['future_parser_function'] = true
obj['puppet_4x_function'] = true
register obj
@ -48,11 +48,11 @@ module Puppetx::Yardoc::YARD::Handlers
# @return [PuppetNamespaceObject]
def function_namespace
# NOTE: This tricky. If there is ever a Ruby class or module with the
# name ::ParserFunctions, then there will be a clash. Hopefully the name
# name ::Puppet4xFunctions, then there will be a clash. Hopefully the name
# is sufficiently uncommon.
obj = P(:root, 'FutureParserFunctions')
obj = P(:root, 'Puppet4xFunctions')
if obj.is_a? Proxy
namespace_obj = PuppetNamespaceObject.new(:root, 'FutureParserFunctions')
namespace_obj = PuppetNamespaceObject.new(:root, 'Puppet4xFunctions')
register namespace_obj
# FIXME: The docstring has to be cleared. Otherwise, the namespace

View File

@ -1,10 +1,10 @@
require 'yard'
require 'puppet/pops'
require_relative '../../yardoc'
require_relative '../../strings'
require_relative '../pops/yard_transformer'
module Puppetx::Yardoc::YARD
module Puppetx::PuppetLabs::Strings::YARD
class PuppetParser < YARD::Parser::Base
attr_reader :file, :source
@ -13,7 +13,7 @@ module Puppetx::Yardoc::YARD
@file = filename
@parser = Puppet::Pops::Parser::Parser.new()
@transformer = Puppetx::Yardoc::Pops::YARDTransformer.new()
@transformer = Puppetx::PuppetLabs::Strings::Pops::YARDTransformer.new()
end
def parse

View File

@ -10,10 +10,10 @@ require_relative 'parser'
require_relative 'handlers'
YARD::Parser::SourceParser.register_parser_type(:puppet,
Puppetx::Yardoc::YARD::PuppetParser,
Puppetx::PuppetLabs::Strings::YARD::PuppetParser,
['pp'])
YARD::Handlers::Processor.register_handler_namespace(:puppet,
Puppetx::Yardoc::YARD::Handlers)
Puppetx::PuppetLabs::Strings::YARD::Handlers)
# FIXME: Might not be the best idea to have the template code on the Ruby
# LOAD_PATH as the contents of this directory really aren't library code.

View File

@ -0,0 +1,21 @@
<% unless P(:root, 'Puppet3xFunctions').is_a?(CodeObjects::Proxy) %>
<li>
<a class='toggle'></a>
<%= link_object(P(:root, 'Puppet3xFunctions'), 'Puppet 3x Functions', nil, false) %>
<small class='search_info'>Puppet3xFunctions</small>
</li>
<ul>
<%= namespace_list(:root => P(:root,'Puppet3xFunctions'), :namespace_types => [:puppetnamespace, :method]) %>
</ul>
<% end %>
<% unless P(:root, 'Puppet4xFunctions').is_a?(CodeObjects::Proxy) %>
<li>
<a class='toggle'></a>
<%= link_object(P(:root, 'Puppet4xFunctions'), 'Puppet 4x Functions', nil, false) %>
<small class='search_info'>Puppet4xFunctions</small>
</li>
<ul>
<%= namespace_list(:root => P(:root,'Puppet4xFunctions'), :namespace_types => [:puppetnamespace, :method]) %>
</ul>
<% end %>

View File

@ -1,13 +0,0 @@
require 'puppetx'
# Nothing to see here except forward declarations.
module Puppetx::Yardoc
# This submodule contains bits that interface with the YARD plugin system.
module YARD
end
# This submodule contains bits that operate on the Pops module produced by
# the Future parser.
module Pops
end
end

View File

@ -1,21 +0,0 @@
<% unless P(:root, 'ParserFunctions').is_a?(CodeObjects::Proxy) %>
<li>
<a class='toggle'></a>
<%= link_object(P(:root, 'ParserFunctions'), 'Parser Functions', nil, false) %>
<small class='search_info'>ParserFunctions</small>
</li>
<ul>
<%= namespace_list(:root => P(:root,'ParserFunctions'), :namespace_types => [:puppetnamespace, :method]) %>
</ul>
<% end %>
<% unless P(:root, 'FutureParserFunctions').is_a?(CodeObjects::Proxy) %>
<li>
<a class='toggle'></a>
<%= link_object(P(:root, 'FutureParserFunctions'), 'Future Parser Functions', nil, false) %>
<small class='search_info'>FutureParserFunctions</small>
</li>
<ul>
<%= namespace_list(:root => P(:root,'FutureParserFunctions'), :namespace_types => [:puppetnamespace, :method]) %>
</ul>
<% end %>

View File

@ -1,10 +1,10 @@
{
"name": "sharpie-puppet_yardoc",
"name": "puppetlabs-strings",
"version": "0.0.1",
"author": "Charlie Sharpsteen",
"author": "Puppet Labs",
"summary": "Puppet documentation via YARD",
"license": "Apache 2.0",
"source": "",
"source": "https://github.com/puppetlabs/puppetlabs-strings",
"project_page": null,
"issues_url": null,
"requirements": [

View File

@ -6,7 +6,7 @@ require 'puppet'
require 'rspec'
# This is neeeded so we can access a Registry if YARD creates one
require 'puppetx/yardoc/yard/plugin'
require 'puppetx/puppetlabs/strings/yard/plugin'
include YARD
RSpec.configure do |config|

View File

@ -1,5 +1,5 @@
require 'spec_helper'
require 'puppet/face/yardoc'
require 'puppet/face/strings'
require 'rspec-html-matchers'
require 'tmpdir'
require 'stringio'
@ -9,26 +9,26 @@ describe Puppet::Face do
describe "YARDoc action" do
it "should raise an error if yard is absent" do
Puppet.features.stubs(:yard?).returns(false)
expect{Puppet::Face[:yardoc, :current].yardoc}.to raise_error(RuntimeError, "The 'yard' gem must be installed in order to use this face.")
expect{Puppet::Face[:strings, :current].yardoc}.to raise_error(RuntimeError, "The 'yard' gem must be installed in order to use this face.")
end
it "should raise an error if rgen is absent" do
Puppet.features.stubs(:rgen?).returns(false)
expect{Puppet::Face[:yardoc, :current].yardoc}.to raise_error(RuntimeError, "The 'rgen' gem must be installed in order to use this face.")
expect{Puppet::Face[:strings, :current].yardoc}.to raise_error(RuntimeError, "The 'rgen' gem must be installed in order to use this face.")
end
it "should raise an error if the Ruby verion is less than 1.9", :if => RUBY_VERSION.match(/^1\.8/) do
expect{Puppet::Face[:yardoc, :current].yardoc}.to raise_error(RuntimeError, "This face requires Ruby 1.9 or greater.")
expect{Puppet::Face[:strings, :current].yardoc}.to raise_error(RuntimeError, "This face requires Ruby 1.9 or greater.")
end
it "should invoke Yardoc with MODULE_SOURCEFILES if no arguments are provided" do
YARD::CLI::Yardoc.expects(:run).with('manifests/**/*.pp', 'lib/**/*.rb')
Puppet::Face[:yardoc, :current].yardoc
Puppet::Face[:strings, :current].yardoc
end
it "should invoke Yardoc with provided arguments" do
YARD::CLI::Yardoc.expects(:run).with('--debug', 'some_file.rb')
Puppet::Face[:yardoc, :current].yardoc('--debug', 'some_file.rb')
Puppet::Face[:strings, :current].yardoc('--debug', 'some_file.rb')
end
describe "when generating HTML for documentation" do
@ -39,7 +39,7 @@ describe Puppet::Face do
using_module('test') do |tmp|
Dir.chdir('test')
Puppet::Face[:yardoc, :current].yardoc
Puppet::Face[:strings, :current].yardoc
expect(read_html(tmp, 'test', 'test.html')).to have_tag('.docstring .discussion', :text => /This class/)
end
@ -49,9 +49,9 @@ describe Puppet::Face do
using_module('test') do |tmp|
Dir.chdir('test')
Puppet::Face[:yardoc, :current].yardoc
Puppet::Face[:strings, :current].yardoc
expect(read_html(tmp, 'test', 'ParserFunctions.html')).to have_tag('.docstring .discussion', :text => /documentation for `function3x`/)
expect(read_html(tmp, 'test', 'Puppet3xFunctions.html')).to have_tag('.docstring .discussion', :text => /documentation for `function3x`/)
end
end
@ -59,7 +59,7 @@ describe Puppet::Face do
using_module('test') do |tmp|
Dir.chdir('test')
Puppet::Face[:yardoc, :current].yardoc
Puppet::Face[:strings, :current].yardoc
expect(read_html(tmp, 'test', 'test.html')).to have_tag('.docstring .discussion', :text => /This class/)
end
@ -70,32 +70,32 @@ describe Puppet::Face do
describe "modules action" do
it "should raise an error if yard is absent" do
Puppet.features.stubs(:yard?).returns(false)
expect{Puppet::Face[:yardoc, :current].modules}.to raise_error(RuntimeError, "The 'yard' gem must be installed in order to use this face.")
expect{Puppet::Face[:strings, :current].modules}.to raise_error(RuntimeError, "The 'yard' gem must be installed in order to use this face.")
end
it "should raise an error if rgen is absent" do
Puppet.features.stubs(:rgen?).returns(false)
expect{Puppet::Face[:yardoc, :current].modules}.to raise_error(RuntimeError, "The 'rgen' gem must be installed in order to use this face.")
expect{Puppet::Face[:strings, :current].modules}.to raise_error(RuntimeError, "The 'rgen' gem must be installed in order to use this face.")
end
it "should raise an error if the Ruby version is less than 1.9", :if => RUBY_VERSION.match(/^1\.8/) do
expect{Puppet::Face[:yardoc, :current].modules}.to raise_error(RuntimeError, "This face requires Ruby 1.9 or greater.")
expect{Puppet::Face[:strings, :current].modules}.to raise_error(RuntimeError, "This face requires Ruby 1.9 or greater.")
end
end
describe "server action" do
it "should raise an error if yard is absent" do
Puppet.features.stubs(:yard?).returns(false)
expect{Puppet::Face[:yardoc, :current].server}.to raise_error(RuntimeError, "The 'yard' gem must be installed in order to use this face.")
expect{Puppet::Face[:strings, :current].server}.to raise_error(RuntimeError, "The 'yard' gem must be installed in order to use this face.")
end
it "should raise an error if rgen is absent" do
Puppet.features.stubs(:rgen?).returns(false)
expect{Puppet::Face[:yardoc, :current].server}.to raise_error(RuntimeError, "The 'rgen' gem must be installed in order to use this face.")
expect{Puppet::Face[:strings, :current].server}.to raise_error(RuntimeError, "The 'rgen' gem must be installed in order to use this face.")
end
it "should raise an error if the Ruby version is less than 1.9", :if => RUBY_VERSION.match(/^1\.8/) do
expect{Puppet::Face[:yardoc, :current].server}.to raise_error(RuntimeError, "This face requires Ruby 1.9 or greater.")
expect{Puppet::Face[:strings, :current].server}.to raise_error(RuntimeError, "This face requires Ruby 1.9 or greater.")
end
end

View File

@ -1,13 +1,13 @@
require 'spec_helper'
require 'puppetx/yardoc/pops/yard_statement'
require 'puppetx/puppetlabs/strings/pops/yard_statement'
describe Puppetx::Yardoc::Pops do
describe Puppetx::PuppetLabs::Strings::Pops do
let(:parser) {Puppet::Pops::Parser::Parser.new()}
describe "YARDstatement class" do
let(:manifest) {"#hello world\nclass foo { }"}
let(:model) {parser.parse_string(manifest).current.definitions.first}
let(:test_statement) {Puppetx::Yardoc::Pops::YARDStatement.new(model)}
let(:test_statement) {Puppetx::PuppetLabs::Strings::Pops::YARDStatement.new(model)}
describe "when creating a new instance of YARDStatement" do
it "should extract comments from the source code" do
@ -19,13 +19,13 @@ describe Puppetx::Yardoc::Pops do
describe "YARDTransfomer class" do
let(:manifest) {"#hello world\nclass foo($bar) { }"}
let(:manifest_default) {"#hello world\nclass foo($bar = 3) { }"}
let(:transformer) {Puppetx::Yardoc::Pops::YARDTransformer.new}
let(:transformer) {Puppetx::PuppetLabs::Strings::Pops::YARDTransformer.new}
describe "transform method" do
it "should perform the correct transformation with parameter defaults" do
model = parser.parse_string(manifest_default).current.definitions.first
statements = transformer.transform(model)
expect(statements.parameters[0][0].class).to be(Puppetx::Yardoc::Pops::YARDStatement)
expect(statements.parameters[0][0].class).to be(Puppetx::PuppetLabs::Strings::Pops::YARDStatement)
end
it "should perform the correct transofmration without parameter defaults" do

View File

@ -1,5 +1,5 @@
require 'spec_helper'
require 'puppetx/yardoc/yard/handlers/defined_type_handler'
require 'puppetx/puppetlabs/strings/yard/handlers/defined_type_handler'
require 'strings_spec/parsing'

View File

@ -1,16 +1,16 @@
require 'spec_helper'
require 'puppetx/yardoc/yard/handlers/future_parser_function_handler'
require 'puppetx/puppetlabs/strings/yard/handlers/puppet_4x_function_handler'
require 'strings_spec/parsing'
describe "FutureParserDispatchHandler" do
describe "Pupet4xFunctionHandler" do
include StringsSpec::Parsing
def the_method()
Registry.at("FutureParserFunctions#the_function")
Registry.at("Puppet4xFunctions#the_function")
end
def the_namespace()
Registry.at("FutureParserFunctions")
Registry.at("Puppet4xFunctions")
end
it "should parse single-line documentation strings before a given function" do

View File

@ -1,5 +1,5 @@
require 'spec_helper'
require 'puppetx/yardoc/yard/handlers/host_class_handler'
require 'puppetx/puppetlabs/strings/yard/handlers/host_class_handler'
require 'strings_spec/parsing'
describe "HostClassDefintion" do

View File

@ -1,16 +1,16 @@
require 'spec_helper'
require 'puppetx/yardoc/yard/handlers/parser_function_handler'
require 'puppetx/puppetlabs/strings/yard/handlers/puppet_3x_function_handler'
require 'strings_spec/parsing'
describe "ParserFunctionHanlder" do
describe "Puppet3xFunctionHanlder" do
include StringsSpec::Parsing
def the_method()
Registry.at("ParserFunctions#the_function")
Registry.at("Puppet3xFunctions#the_function")
end
def the_namespace()
Registry.at("ParserFunctions")
Registry.at("Puppet3xFunctions")
end
it "should parse single-line documentation strings before a given function" do