openstax_kitchen 2.0.0 → 3.0.0

data/lib/kitchen/page_element.rb

@@ -1,6 +1,15 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for a page
+  #
   class PageElement < ElementBase
 
+    # Creates a new +PageElement+
+    #
+    # @param node [Nokogiri::XML::Node] the node this element wraps
+    # @param document [Document] this element's document
+    #
     def initialize(node:, document: nil)
       super(node: node,
             document: document,
@@ -8,43 +17,83 @@ module Kitchen
             short_type: :page)
     end
 
+    # Returns the title element.  This method is aware that the title of the
+    # introduction page moves during the baking process.
+    #
+    # @raise [ElementNotFoundError] if no matching element is found
+    # @return [Element]
+    #
     def title
       # The selector for intro titles changes during the baking process
-      first!(is_introduction? ?
-               selectors.title_in_introduction_page :
-               selectors.title_in_page)
+      first!(is_introduction? ? selectors.title_in_introduction_page : selectors.title_in_page)
+    end
+
+    # Returns an enumerator for titles.
+    #
+    # @return [ElementEnumerator]
+    #
+    def titles
+      search("div[data-type='document-title']")
     end
 
+    # Returns true if this page is an introduction
+    #
+    # @return [Boolean]
+    #
     def is_introduction?
-      has_class?("introduction")
+      has_class?('introduction')
     end
 
+    # Returns true if this page is a preface
+    #
+    # @return [Boolean]
+    #
     def is_preface?
-      has_class?("preface")
+      has_class?('preface')
     end
 
+    # Returns true if this page is an appendix
+    #
+    # @return [Boolean]
+    #
     def is_appendix?
-      has_class?("appendix")
+      has_class?('appendix')
     end
 
+    # Returns the metadata element.
+    #
+    # @raise [ElementNotFoundError] if no matching element is found
+    # @return [Element]
+    #
     def metadata
       first!("div[data-type='metadata']")
     end
 
+    # Returns the summary element.
+    #
+    # @raise [ElementNotFoundError] if no matching element is found
+    # @return [Element]
+    #
     def summary
-      first!("section.summary")
+      first!(selectors.page_summary)
     end
 
+    # Returns the exercises element.
+    #
+    # @raise [ElementNotFoundError] if no matching element is found
+    # @return [Element]
+    #
     def exercises
-      first!("section.exercises")
-    end
-
-    def exercises_section
-      search("")
+      first!('section.exercises')
     end
 
+    # Returns true if this class represents the element for the given node
+    #
+    # @param node [Nokogiri::XML::Node] the underlying node
+    # @return [Boolean]
+    #
     def self.is_the_element_class_for?(node)
-      node['data-type'] == "page"
+      node['data-type'] == 'page'
     end
 
   end

data/lib/kitchen/page_element_enumerator.rb

@@ -1,9 +1,17 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An enumerator for page elements
+  #
   class PageElementEnumerator < ElementEnumeratorBase
 
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
     def self.factory
       ElementEnumeratorFactory.new(
-        default_css_or_xpath: "div[data-type='page']", # TODO get from config?
+        default_css_or_xpath: "div[data-type='page']", # TODO: get from config?
         sub_element_class: PageElement,
         enumerator_class: self
       )

data/lib/kitchen/pantry.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Kitchen
   # A place to store labeled items during recipe work.  Essentially, a slightly
   # improved hash.
@@ -5,22 +7,47 @@ module Kitchen
   class Pantry
     include Enumerable
 
+    # Adds an item to the pantry with the provided label
+    #
+    # @param item [Object] something to store
+    # @param label [String, Symbol] a label with which to retrieve this item later.
     def store(item, label:)
       @hash[label.to_sym] = item
     end
 
+    # Get an item from the pantry
+    #
+    # @param label [String, Symbol] the item's label
+    # @return [Object]
+    #
     def get(label)
       @hash[label.to_sym]
     end
 
+    # Get an item from the pantry, raising if not present
+    #
+    # @param label [String, Symbol] the item's label
+    # @raise [RecipeError] if there's no item for the label
+    # @return [Object]
+    #
     def get!(label)
       get(label) || raise(RecipeError, "There is no pantry item labeled '#{label}'")
     end
 
+    # Iterate over the pantry items
+    #
+    # @yield Gives each label and item pair to the block
+    # @yieldparam label [Symbol] the item's label
+    # @yieldparam item [Object] the item
+    #
     def each(&block)
-      @hash.each{|k,v| block.call(k,v)}
+      @hash.each { |k, v| block.call(k, v) }
     end
 
+    # Returns the number of items in the pantry
+    #
+    # @return [Integer]
+    #
     def size
       @hash.keys.size
     end

data/lib/kitchen/patches/nokogiri.rb

@@ -1,16 +1,27 @@
+# frozen_string_literal: true
+
 # Make debug output more useful (dumping entire document out is not useful)
 module Nokogiri
   module XML
+    # Monkey patches for Nokogiri::XML::Document
+    # @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Document Nokogiri::XML::Document
     class Document
+      # Hides the guts of the document when printed out so you don't get 5MB dumped into your
+      # terminal
+      #
       def inspect
-        "Nokogiri::XML::Document <hidden for brevity>"
+        'Nokogiri::XML::Document <hidden for brevity>'
       end
 
+      # Alphabetizes all attributes within the document, useful for comparing one
+      # document to another (since attribute order isn't meaningful)
+      #
       def alphabetize_attributes!
         traverse do |child|
           next if child.text? || child.document?
+
           child_attributes = child.attributes
-          child_attributes.each do |key, value|
+          child_attributes.each do |key, _value|
             child.remove_attribute(key)
           end
           sorted_keys = child_attributes.keys.sort
@@ -22,7 +33,13 @@ module Nokogiri
       end
     end
 
+    # Monkey patches for Nokogiri::XML::Node
+    # @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node Nokogiri::XML::Node
     class Node
+      # Calls to_s on the node
+      #
+      # @return [String]
+      #
       def inspect
         to_s
       end

data/lib/kitchen/patches/renderable.rb

@@ -1,6 +1,13 @@
+# frozen_string_literal: true
+
+# Monkey patches for +Object+
+#
 class Object
 
   # Adds a `render` method to a class for rendering an ERB template to a string.
+  #
+  # @param dir [String] a directory in which to find the template to be rendered,
+  #   populated with a guess from the call stack if not provided.
   def self.renderable(dir: nil)
     dir ||= begin
       this_patch_file = __FILE__
@@ -8,11 +15,11 @@ class Object
         location.absolute_path == this_patch_file
       end
 
-      location_that_called_renderable = caller_locations[(this_patch_file_caller_index || -1)+1]
+      location_that_called_renderable = caller_locations[(this_patch_file_caller_index || -1) + 1]
       File.dirname(location_that_called_renderable.path)
     end
 
-    class_eval <<~METHOD
+    class_eval <<~METHOD, __FILE__, __LINE__ + 1
       def renderable_base_dir
         "#{dir}"
       end
@@ -25,7 +32,6 @@ class Object
         ERB.new(template).result(binding)
       end
     end
-
   end
 
 end

data/lib/kitchen/patches/string.rb

@@ -1,4 +1,12 @@
+# frozen_string_literal: true
+
+# Monkey patches for +String+
+#
 class String
+  # Downcases the first letter of self, returning a new string
+  #
+  # @return [String]
+  #
   def uncapitalize
     sub(/^[A-Z]/, &:downcase)
   end

data/lib/kitchen/recipe.rb

@@ -1,9 +1,24 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An object that yields a +Document+ for modification (those modifications are
+  # the "recipe")
+  #
   class Recipe
 
+    # The document the recipe makes available for modification
+    # @return [Document]
     attr_reader :document
+
+    # The file location of the recipe
+    # @return [String]
     attr_reader :source_location
 
+    # Sets the document so the recipe can yield it for modification
+    #
+    # @param document [Document] the document to modify
+    # @raise [StandardError] if not passed supported document type
+    #
     def document=(document)
       @document =
         case document
@@ -16,57 +31,46 @@ module Kitchen
 
     # Make a new Recipe
     #
+    # @yield A block for defining the steps of the recipe
     # @yieldparam doc [Document] an object representing an XML document
     #
     def initialize(&block)
+      raise(RecipeError, 'Recipes must be initialized with a block') unless block_given?
+
       @source_location = block.source_location[0]
       @block = block
     end
 
-    def node!
-      node || raise("The recipe's node has not been set")
-    end
-
+    # Executes the block given to +Recipe.new+ on the document.  Aka, does the baking.
+    #
     def bake
-      begin
-        @block.to_proc.call(document)
-      rescue RecipeError => ee
-        print_recipe_error_and_exit(ee)
-      rescue ArgumentError => ee
-        if if_any_stack_file_matches_source_location?(ee)
-          print_recipe_error_and_exit(ee)
-        else
-          raise
-        end
-      rescue NoMethodError => ee
-        if if_any_stack_file_matches_source_location?(ee)
-          print_recipe_error_and_exit(ee)
-        else
-          raise
-        end
-      rescue NameError => ee
-        if if_stack_starts_with_source_location?(ee)
-          print_recipe_error_and_exit(ee)
-        else
-          raise
-        end
-      rescue ElementNotFoundError => ee
-        print_recipe_error_and_exit(ee)
-      rescue Nokogiri::CSS::SyntaxError => ee
-        print_recipe_error_and_exit(ee)
-      end
+      @block.to_proc.call(document)
+    rescue RecipeError, ElementNotFoundError, Nokogiri::CSS::SyntaxError => e
+      print_recipe_error_and_exit(e)
+    rescue ArgumentError, NoMethodError => e
+      raise unless any_stack_file_matches_source_location?(e)
+
+      print_recipe_error_and_exit(e)
+    rescue NameError => e
+      raise unless stack_starts_with_source_location?(e)
+
+      print_recipe_error_and_exit(e)
     end
 
     protected
 
-    def if_stack_starts_with_source_location?(error)
+    def stack_starts_with_source_location?(error)
       error.backtrace.first.start_with?(source_location)
     end
 
-    def if_any_stack_file_matches_source_location?(error)
-      error.backtrace.any? {|entry| entry.start_with?(@source_location)}
+    def any_stack_file_matches_source_location?(error)
+      error.backtrace.any? { |entry| entry.start_with?(@source_location) }
     end
 
+    # Print the given recipe error and do a process exit
+    #
+    # @param error [RecipeError] the error
+    #
     def print_recipe_error_and_exit(error)
       Kitchen::Debug.print_recipe_error(error: error,
                                         source_location: source_location,

data/lib/kitchen/search_history.rb

@@ -1,31 +1,70 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # Records the search history that was used to find a certain element
+  #
   class SearchHistory
     attr_reader :latest
     attr_reader :upstream
 
+    # Returns an empty search history
+    #
+    # @return [SearchHistory]
+    #
     def self.empty
       new
     end
 
-    def add(css_or_xpath)
-      self.class.new(self, css_or_xpath.nil? ? nil : [css_or_xpath].join(", "))
+    # Returns a new +SearchHistory+ that contains the current history plus the
+    # provided query
+    #
+    # @param search_query [SearchQuery] the search query to add to the history
+    # @return [SearchHistory]
+    #
+    def add(search_query)
+      search_query = SearchQuery.new(css_or_xpath: search_query) if search_query.is_a?(String)
+      self.class.new(self, search_query)
     end
 
-    def to_s(missing_string="?")
-      to_a.map{|item| "[#{item || missing_string}]"}.join(" ")
+    # Returns the history as a string
+    #
+    # @param missing_string [String] if there's a missing part of the history, this string
+    #   is used in its place
+    # @return [String]
+    #
+    def to_s(missing_string='?')
+      array = to_a
+      array.shift while array.any? && array[0].nil?
+      array.map { |item| "[#{item || missing_string}]" }.join(' ')
     end
 
+    # Returns this instance as an array of selectors
+    #
+    # @return [Array<String>]
+    #
     def to_a
       empty? ? [] : [upstream&.to_a || [], latest].flatten
     end
 
+    # Returns true if the search history is empty
+    #
+    # @return [Boolean]
+    #
     def empty?
       upstream.nil? && latest.nil?
     end
 
     protected
 
+    # Create a new instance
+    #
+    # @param upstream [SearchHistory] prior search history
+    # @param latest [SearchQuery] the new history
+    #
     def initialize(upstream=nil, latest=nil)
+      raise 'Upstream must be a SearchHistory' unless upstream.nil? || upstream.is_a?(SearchHistory)
+      raise 'Latest must be a SearchQuery' unless latest.nil? || latest.is_a?(SearchQuery)
+
       @upstream = upstream
       @latest = latest
     end