This doesn't cover all the code, only the part that interacts with Puppet internals which is what matters when Puppet changes. This patch also contains an integration test.
Signed-off-by: Brice Figureau <[email protected]> --- lib/puppet/util/rdoc/parser.rb | 10 +- spec/integration/util/rdoc/parser.rb | 42 +++ spec/unit/util/rdoc.rb | 153 +++++++++++ spec/unit/util/rdoc/parser.rb | 461 ++++++++++++++++++++++++++++++++++ 4 files changed, 661 insertions(+), 5 deletions(-) create mode 100755 spec/integration/util/rdoc/parser.rb create mode 100755 spec/unit/util/rdoc.rb create mode 100755 spec/unit/util/rdoc/parser.rb diff --git a/lib/puppet/util/rdoc/parser.rb b/lib/puppet/util/rdoc/parser.rb index 842b81c..5fc350a 100644 --- a/lib/puppet/util/rdoc/parser.rb +++ b/lib/puppet/util/rdoc/parser.rb @@ -15,6 +15,8 @@ module RDoc class Parser extend ParserFactory + attr_accessor :ast, :input_file_name, :top_level + # parser registration into RDoc parse_files_matching(/\.(rb|pp)$/) @@ -39,8 +41,6 @@ class Parser @top_level end - private - # Due to a bug in RDoc, we need to roll our own find_module_named # The issue is that RDoc tries harder by asking the parent for a class/module # of the name. But by doing so, it can mistakenly use a module of same name @@ -285,8 +285,8 @@ class Parser # register method into the container meth = AnyMethod.new(declaration, name) - container.add_method(meth) meth.comment = define.doc + container.add_method(meth) look_for_directives_in(container, meth.comment) unless meth.comment.empty? meth.params = "( " + declaration + " )" meth.visibility = :public @@ -304,7 +304,7 @@ class Parser unless name.empty? document_class(name,klass,container) else # on main class document vardefs - code = klass.code.children unless klass.code.is_a?(Puppet::Parser::AST::ASTArray) + code = klass.code.children if klass.code.is_a?(Puppet::Parser::AST::ASTArray) code ||= klass.code scan_for_vardef(container, code) unless code.nil? end @@ -345,9 +345,9 @@ class Parser comments += $1 + "\n" elsif line =~ /^[ \t]*Facter.add\(['"](.*?)['"]\)/ current_fact = Fact.new($1,{}) - container.add_fact(current_fact) look_for_directives_in(container, comments) unless comments.empty? current_fact.comment = comments + container.add_fact(current_fact) current_fact.record_location(@top_level) comments = "" Puppet.debug "rdoc: found custom fact %s" % current_fact.name diff --git a/spec/integration/util/rdoc/parser.rb b/spec/integration/util/rdoc/parser.rb new file mode 100755 index 0000000..df8c62d --- /dev/null +++ b/spec/integration/util/rdoc/parser.rb @@ -0,0 +1,42 @@ +#!/usr/bin/env ruby + +Dir.chdir(File.dirname(__FILE__)) { (s = lambda { |f| File.exist?(f) ? require(f) : Dir.chdir("..") { s.call(f) } }).call("spec/spec_helper.rb") } + +require 'puppet/parser/loaded_code' +require 'puppet/util/rdoc/parser' +require 'puppet/util/rdoc' +require 'puppet/util/rdoc/code_objects' +require 'rdoc/options' +require 'rdoc/rdoc' + +describe RDoc::Parser do + require 'puppet_spec/files' + include PuppetSpec::Files + + before :each do + tmpdir = tmpfile('rdoc_parser_tmp') + Dir.mkdir(tmpdir) + @parsedfile = File.join(tmpdir, 'init.pp') + + File.open(@parsedfile, 'w') do |f| + f.puts '# comment' + f.puts 'class ::test {}' + end + + @top_level = stub_everything 'toplevel', :file_relative_name => @parsedfile + @module = stub_everything 'module' + @puppet_top_level = RDoc::PuppetTopLevel.new(@top_level) + RDoc::PuppetTopLevel.stubs(:new).returns(@puppet_top_level) + @puppet_top_level.expects(:add_module).returns(@module) + @parser = RDoc::Parser.new(@top_level, @parsedfile, nil, Options.instance, RDoc::Stats.new) + end + + after(:each) do + File.unlink(@parsedfile) + end + + it "should parse to RDoc data structure" do + @parser.expects(:document_class).with { |n,k,c| n == "::test" and k.is_a?(Puppet::Parser::AST::HostClass) } + @parser.scan + end +end \ No newline at end of file diff --git a/spec/unit/util/rdoc.rb b/spec/unit/util/rdoc.rb new file mode 100755 index 0000000..eeaaa32 --- /dev/null +++ b/spec/unit/util/rdoc.rb @@ -0,0 +1,153 @@ +#!/usr/bin/env ruby + +Dir.chdir(File.dirname(__FILE__)) { (s = lambda { |f| File.exist?(f) ? require(f) : Dir.chdir("..") { s.call(f) } }).call("spec/spec_helper.rb") } + +require 'puppet/util/rdoc' +require 'rdoc/rdoc' + +describe Puppet::Util::RDoc do + + describe "when generating RDoc HTML documentation" do + before :each do + @rdoc = stub_everything 'rdoc' + RDoc::RDoc.stubs(:new).returns(@rdoc) + end + + it "should tell the parser to ignore import" do + Puppet.expects(:[]=).with(:ignoreimport, true) + + Puppet::Util::RDoc.rdoc("output", []) + end + + it "should install the Puppet HTML Generator into RDoc generators" do + Puppet::Util::RDoc.rdoc("output", []) + + RDoc::RDoc::GENERATORS["puppet"].file_name.should == "puppet/util/rdoc/generators/puppet_generator.rb" + end + + it "should tell RDoc to generate documentation using the Puppet generator" do + @rdoc.expects(:document).with { |args| args.include?("--fmt") and args.include?("puppet") } + + Puppet::Util::RDoc.rdoc("output", []) + end + + it "should tell RDoc to be quiet" do + @rdoc.expects(:document).with { |args| args.include?("--quiet") } + + Puppet::Util::RDoc.rdoc("output", []) + end + + it "should tell RDoc to force updates of indices" do + @rdoc.expects(:document).with { |args| args.include?("--force-update") } + + Puppet::Util::RDoc.rdoc("output", []) + end + + it "should tell RDoc to use the given outputdir" do + @rdoc.expects(:document).with { |args| args.include?("--op") and args.include?("myoutputdir") } + + Puppet::Util::RDoc.rdoc("myoutputdir", []) + end + + it "should give all the source directories to RDoc" do + @rdoc.expects(:document).with { |args| args.include?("sourcedir") } + + Puppet::Util::RDoc.rdoc("output", ["sourcedir"]) + end + end + + describe "when running a manifest documentation" do + it "should tell the parser to ignore import" do + Puppet.expects(:[]=).with(:ignoreimport, true) + + Puppet::Util::RDoc.manifestdoc([]) + end + + it "should puppet parse all given files" do + FileTest.stubs(:file?).returns(true) + Puppet::Util::RDoc.stubs(:output) + + parser = stub_everything + Puppet::Parser::Parser.stubs(:new).returns(parser) + + parser.expects(:file=).with("file") + parser.expects(:parse) + + Puppet::Util::RDoc.manifestdoc(["file"]) + end + + it "should call output for each parsed file" do + FileTest.stubs(:file?).returns(true) + + ast = stub_everything + parser = stub_everything + Puppet::Parser::Parser.stubs(:new).returns(parser) + parser.stubs(:parse).returns(ast) + + Puppet::Util::RDoc.expects(:output).with("file", ast) + + Puppet::Util::RDoc.manifestdoc(["file"]) + end + + describe "when outputing documentation" do + before :each do + @node = stub 'node', :file => "file", :line => 1, :doc => "" + @class = stub 'class', :file => "file", :line => 4, :doc => "" + @definition = stub 'definition', :file => "file", :line => 3, :doc => "" + @ast = stub 'ast', :nodes => { :node => @node }, :hostclasses => { :class => @class }, :definitions => { :definition => @definition } + end + + it "should output doc for ast nodes" do + @node.expects(:doc) + + Puppet::Util::RDoc.output("file", @ast) + end + + it "should output doc for ast classes" do + @class.expects(:doc) + + Puppet::Util::RDoc.output("file", @ast) + end + + it "should output doc for ast definitions" do + @definition.expects(:doc) + + Puppet::Util::RDoc.output("file", @ast) + end + + it "should output doc in order of increasing line number" do + byline = sequence('byline') + @node.expects(:doc).in_sequence(byline) + @definition.expects(:doc).in_sequence(byline) + @class.expects(:doc).in_sequence(byline) + + Puppet::Util::RDoc.output("file", @ast) + end + + it "should not output documentation of ast object of another node" do + klass = stub 'otherclass', :file => "otherfile", :line => 12, :doc => "" + @ast.stubs(:hostclasses).returns({ :otherclass => klass }) + + klass.expects(:doc).never + + Puppet::Util::RDoc.output("file", @ast) + end + + it "should output resource documentation if needed" do + Puppet.settings.stubs(:[]).with(:document_all).returns(true) + [...@node,@definition].each do |o| + o.stubs(:code).returns([]) + end + + resource = stub_everything 'resource', :line => 1 + resource.stubs(:is_a?).with(Puppet::Parser::AST::ASTArray).returns(false) + resource.stubs(:is_a?).with(Puppet::Parser::AST::Resource).returns(true) + @class.stubs(:code).returns([resource]) + + resource.expects(:doc) + + Puppet::Util::RDoc.output("file", @ast) + end + end + end +end diff --git a/spec/unit/util/rdoc/parser.rb b/spec/unit/util/rdoc/parser.rb new file mode 100755 index 0000000..b05df6d --- /dev/null +++ b/spec/unit/util/rdoc/parser.rb @@ -0,0 +1,461 @@ +#!/usr/bin/env ruby + +Dir.chdir(File.dirname(__FILE__)) { (s = lambda { |f| File.exist?(f) ? require(f) : Dir.chdir("..") { s.call(f) } }).call("spec/spec_helper.rb") } + +require 'puppet/parser/loaded_code' +require 'puppet/util/rdoc/parser' +require 'puppet/util/rdoc/code_objects' +require 'rdoc/options' +require 'rdoc/rdoc' + +describe RDoc::Parser do + before :each do + File.stubs(:stat).with("init.pp") + @top_level = stub_everything 'toplevel', :file_relative_name => "init.pp" + @parser = RDoc::Parser.new(@top_level, "module/manifests/init.pp", nil, Options.instance, RDoc::Stats.new) + end + + describe "when scanning files" do + it "should parse puppet files with the puppet parser" do + @parser.stubs(:scan_top_level) + parser = stub 'parser' + Puppet::Parser::Parser.expects(:new).returns(parser) + parser.expects(:parse) + parser.expects(:file=).with("module/manifests/init.pp") + + @parser.scan + end + + it "should scan the ast for Puppet files" do + parser = stub_everything 'parser' + Puppet::Parser::Parser.stubs(:new).returns(parser) + + @parser.expects(:scan_top_level) + + @parser.scan + end + + it "should return a PuppetTopLevel to RDoc" do + parser = stub_everything 'parser' + Puppet::Parser::Parser.stubs(:new).returns(parser) + + @parser.expects(:scan_top_level) + + @parser.scan.should be_a(RDoc::PuppetTopLevel) + end + end + + describe "when scanning top level entities" do + before :each do + @loadedcode = stub_everything 'loadedcode' + @parser.ast = @loadedcode + @parser.stubs(:split_module).returns("module") + + @topcontainer = stub_everything 'topcontainer' + @container = stub_everything 'container' + @module = stub_everything 'module' + @container.stubs(:add_module).returns(@module) + @parser.stubs(:get_class_or_module).returns([...@container, "module"]) + end + + it "should read any present README as module documentation" do + FileTest.stubs(:readable?).returns(true) + File.stubs(:open).returns("readme") + @parser.stubs(:parse_elements) + + @module.expects(:comment=).with("readme") + + @parser.scan_top_level(@topcontainer) + end + + it "should tell the container its module name" do + @parser.stubs(:parse_elements) + + @topcontainer.expects(:module_name=).with("module") + + @parser.scan_top_level(@topcontainer) + end + + it "should not document our toplevel if it isn't a valid module" do + @parser.stubs(:split_module).returns(nil) + + @topcontainer.expects(:document_self=).with(false) + @parser.expects(:parse_elements).never + + @parser.scan_top_level(@topcontainer) + end + + it "should set the module as global if we parse the global manifests (ie <site> module)" do + @parser.stubs(:split_module).returns("<site>") + @parser.stubs(:parse_elements) + + @topcontainer.expects(:global=).with(true) + + @parser.scan_top_level(@topcontainer) + end + + it "should attach this module container to the toplevel container" do + @parser.stubs(:parse_elements) + + @container.expects(:add_module).with(RDoc::PuppetModule, "module").returns(@module) + + @parser.scan_top_level(@topcontainer) + end + + it "should defer ast parsing to parse_elements for this module" do + @parser.expects(:parse_elements).with(@module) + + @parser.scan_top_level(@topcontainer) + end + + it "should defer plugins parsing to parse_plugins for this module" do + @parser.input_file_name = "module/plugins/puppet/parser/function.rb" + + @parser.expects(:parse_plugins).with(@module) + + @parser.scan_top_level(@topcontainer) + end + end + + describe "when finding modules from filepath" do + before :each do + Puppet::Module.stubs(:modulepath).returns("/path/to/modules") + end + + it "should return the module name for modulized puppet manifests" do + File.stubs(:expand_path).returns("/path/to/module/manifests/init.pp") + File.stubs(:identical?).with("/path/to", "/path/to/modules").returns(true) + @parser.split_module("/path/to/modules/mymodule/manifests/init.pp").should == "module" + end + + it "should return <site> for manifests not under module path" do + File.stubs(:expand_path).returns("/path/to/manifests/init.pp") + File.stubs(:identical?).returns(false) + @parser.split_module("/path/to/manifests/init.pp").should == "<site>" + end + end + + describe "when parsing AST elements" do + before :each do + @klass = stub_everything 'klass', :file => "module/manifests/init.pp", :classname => "myclass" + @definition = stub_everything 'definition', :file => "module/manifests/init.pp" + @node = stub_everything 'node', :file => "module/manifests/init.pp" + + @loadedcode = Puppet::Parser::LoadedCode.new + @parser.ast = @loadedcode + + @container = stub_everything 'container' + end + + it "should document classes in the parsed file" do + @loadedcode.add_hostclass("myclass", @klass) + + @parser.expects(:document_class).with("myclass", @klass, @container) + + @parser.parse_elements(@container) + end + + it "should not document class parsed in an other file" do + @klass.stubs(:file).returns("/not/same/path/file.pp") + @loadedcode.add_hostclass("myclass", @klass) + + @parser.expects(:document_class).with("myclass", @klass, @container).never + + @parser.parse_elements(@container) + end + + it "should document vardefs for the main class" do + @loadedcode.add_hostclass(:main, @klass) + + code = stub 'code', :is_a? => false + @klass.stubs(:classname).returns("") + @klass.stubs(:code).returns(code) + + @parser.expects(:scan_for_vardef).with(@container, code) + + @parser.parse_elements(@container) + end + + it "should document definitions in the parsed file" do + @loadedcode.add_definition("mydef", @definition) + + @parser.expects(:document_define).with("mydef", @definition, @container) + + @parser.parse_elements(@container) + end + + it "should not document definitions parsed in an other file" do + @definition.stubs(:file).returns("/not/same/path/file.pp") + @loadedcode.add_definition("mydef", @definition) + + @parser.expects(:document_define).with("mydef", @definition, @container).never + + @parser.parse_elements(@container) + end + + it "should document nodes in the parsed file" do + @loadedcode.add_node("mynode", @node) + + @parser.expects(:document_node).with("mynode", @node, @container) + + @parser.parse_elements(@container) + end + + it "should not document node parsed in an other file" do + @node.stubs(:file).returns("/not/same/path/file.pp") + @loadedcode.add_node("mynode", @node) + + @parser.expects(:document_node).with("mynode", @node, @container).never + + @parser.parse_elements(@container) + end + end + + describe "when documenting definition" do + before(:each) do + @define = stub_everything 'define', :arguments => [], :doc => "mydoc" + @class = stub_everything 'class' + @parser.stubs(:get_class_or_module).returns([...@class, "mydef"]) + end + + it "should register a RDoc method to the current container" do + @class.expects(:add_method).with { |m| m.name == "mydef"} + @parser.document_define("mydef", @define, @class) + end + + it "should attach the documentation to this method" do + @class.expects(:add_method).with { |m| m.comment = "mydoc" } + + @parser.document_define("mydef", @define, @class) + end + end + + describe "when documenting nodes" do + before :each do + @code = stub_everything 'code' + @node = stub_everything 'node', :doc => "mydoc", :parentclass => "parent", :code => @code + @rdoc_node = stub_everything 'rdocnode' + + @class = stub_everything 'class' + @class.stubs(:add_node).returns(@rdoc_node) + end + + it "should add a node to the current container" do + @class.expects(:add_node).with("mynode", "parent").returns(@rdoc_node) + @parser.document_node("mynode", @node, @class) + end + + it "should associate the node documentation to the rdoc node" do + @rdoc_node.expects(:comment=).with("mydoc") + @parser.document_node("mynode", @node, @class) + end + + it "should scan for include and require" do + @parser.expects(:scan_for_include_or_require).with(@rdoc_node, @code) + @parser.document_node("mynode", @node, @class) + end + + it "should scan for variable definition" do + @parser.expects(:scan_for_vardef).with(@rdoc_node, @code) + @parser.document_node("mynode", @node, @class) + end + + it "should scan for resources if needed" do + Puppet.settings.stubs(:[]).with(:document_all).returns(true) + @parser.expects(:scan_for_resource).with(@rdoc_node, @code) + @parser.document_node("mynode", @node, @class) + end + end + + describe "when documenting classes" do + before :each do + @code = stub_everything 'code' + @class = stub_everything 'class', :doc => "mydoc", :parentclass => "parent", :code => @code + @rdoc_class = stub_everything 'rdoc-class' + + @module = stub_everything 'class' + @module.stubs(:add_class).returns(@rdoc_class) + @parser.stubs(:get_class_or_module).returns([...@module, "myclass"]) + end + + it "should add a class to the current container" do + @module.expects(:add_class).with(RDoc::PuppetClass, "myclass", "parent").returns(@rdoc_class) + @parser.document_class("mynode", @class, @module) + end + + it "should set the superclass" do + @rdoc_class.expects(:superclass=).with("parent") + @parser.document_class("mynode", @class, @module) + end + + it "should associate the node documentation to the rdoc class" do + @rdoc_class.expects(:comment=).with("mydoc") + @parser.document_class("mynode", @class, @module) + end + + it "should scan for include and require" do + @parser.expects(:scan_for_include_or_require).with(@rdoc_class, @code) + @parser.document_class("mynode", @class, @module) + end + + it "should scan for resources if needed" do + Puppet.settings.stubs(:[]).with(:document_all).returns(true) + @parser.expects(:scan_for_resource).with(@rdoc_class, @code) + @parser.document_class("mynode", @class, @module) + end + end + + describe "when scanning for includes and requires" do + + def create_stmt(name) + stmt_value = stub "#{name}_value", :value => "myclass" + stmt = stub_everything 'stmt', :name => name, :arguments => [stmt_value], :doc => "mydoc" + stmt.stubs(:is_a?).with(Puppet::Parser::AST::ASTArray).returns(false) + stmt.stubs(:is_a?).with(Puppet::Parser::AST::Function).returns(true) + stmt + end + + before(:each) do + @class = stub_everything 'class' + @code = stub_everything 'code' + @code.stubs(:is_a?).with(Puppet::Parser::AST::ASTArray).returns(true) + end + + it "should register recursively includes to the current container" do + @code.stubs(:children).returns([ create_stmt("include") ]) + + @class.expects(:add_include).with { |i| i.is_a?(RDoc::Include) and i.name == "myclass" and i.comment == "mydoc" } + @parser.scan_for_include_or_require(@class, [...@code]) + end + + it "should register requires to the current container" do + @code.stubs(:children).returns([ create_stmt("require") ]) + + @class.expects(:add_require).with { |i| i.is_a?(RDoc::Include) and i.name == "myclass" and i.comment == "mydoc" } + @parser.scan_for_include_or_require(@class, [...@code]) + end + end + + describe "when scanning for variable definition" do + before :each do + @class = stub_everything 'class' + + @stmt = stub_everything 'stmt', :name => "myvar", :value => "myvalue", :doc => "mydoc" + @stmt.stubs(:is_a?).with(Puppet::Parser::AST::ASTArray).returns(false) + @stmt.stubs(:is_a?).with(Puppet::Parser::AST::VarDef).returns(true) + + @code = stub_everything 'code' + @code.stubs(:is_a?).with(Puppet::Parser::AST::ASTArray).returns(true) + end + + it "should recursively register variables to the current container" do + @code.stubs(:children).returns([ @stmt ]) + + @class.expects(:add_constant).with { |i| i.is_a?(RDoc::Constant) and i.name == "myvar" and i.comment == "mydoc" } + @parser.scan_for_vardef(@class, [ @code ]) + end + end + + describe "when scanning for resources" do + before :each do + @class = stub_everything 'class' + + param = stub 'params', :children => [] + @stmt = stub_everything 'stmt', :type => "File", :title => "myfile", :doc => "mydoc", :params => param + @stmt.stubs(:is_a?).with(Puppet::Parser::AST::ASTArray).returns(false) + @stmt.stubs(:is_a?).with(Puppet::Parser::AST::Resource).returns(true) + + @code = stub_everything 'code' + @code.stubs(:is_a?).with(Puppet::Parser::AST::ASTArray).returns(true) + end + + it "should register a PuppetResource to the current container" do + @code.stubs(:children).returns([ @stmt ]) + + @class.expects(:add_resource).with { |i| i.is_a?(RDoc::PuppetResource) and i.title == "myfile" and i.comment == "mydoc" } + @parser.scan_for_resource(@class, [ @code ]) + end + end + + describe "when parsing plugins" do + before :each do + @container = stub 'container' + end + + it "should delegate parsing custom facts to parse_facts" do + @parser = RDoc::Parser.new(@top_level, "module/manifests/plugins/puppet/facter/test.rb", nil, Options.instance, RDoc::Stats.new) + + @parser.expects(:parse_fact).with(@container) + @parser.parse_plugins(@container) + end + + it "should delegate parsing plugins to parse_plugins" do + @parser = RDoc::Parser.new(@top_level, "module/manifests/plugins/puppet/functions/test.rb", nil, Options.instance, RDoc::Stats.new) + + @parser.expects(:parse_puppet_plugin).with(@container) + @parser.parse_plugins(@container) + end + end + + describe "when parsing plugins" do + before :each do + @container = stub_everything 'container' + end + + it "should add custom functions to the container" do + File.stubs(:open).yields("# documentation + module Puppet::Parser::Functions + newfunction(:myfunc, :type => :rvalue) do |args| + File.dirname(args[0]) + end + end".split("\n")) + + @container.expects(:add_plugin).with do |plugin| + plugin.comment == "documentation\n" #and + plugin.name == "myfunc" + end + + @parser.parse_puppet_plugin(@container) + end + + it "should add custom types to the container" do + File.stubs(:open).yields("# documentation + Puppet::Type.newtype(:mytype) do + end".split("\n")) + + @container.expects(:add_plugin).with do |plugin| + plugin.comment == "documentation\n" #and + plugin.name == "mytype" + end + + @parser.parse_puppet_plugin(@container) + end + end + + describe "when parsing facts" do + before :each do + @container = stub_everything 'container' + File.stubs(:open).yields(["# documentation", "Facter.add('myfact') do", "confine :kernel => :linux", "end"]) + end + + it "should add facts to the container" do + @container.expects(:add_fact).with do |fact| + fact.comment == "documentation\n" and + fact.name == "myfact" + end + + @parser.parse_fact(@container) + end + + it "should add confine to the parsed facts" do + ourfact = nil + @container.expects(:add_fact).with do |fact| + ourfact = fact + true + end + + @parser.parse_fact(@container) + ourfact.confine.should == { :type => "kernel", :value => ":linux" } + end + end +end -- 1.6.4 --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Developers" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en -~----------~----~----~----~------~----~------~--~---
