openstax_kitchen 2.0.0 → 3.0.0

data/lib/kitchen/clipboard.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Kitchen
   # A place to store lists of things during recipe work.  Essentially a
   # slightly fancy array.
@@ -5,33 +7,62 @@ module Kitchen
   class Clipboard
     include Enumerable
 
-    attr_reader :items
+    # The underlying array
+    # @return [Array<ElementBase>]
+    #
+    def items
+      @items.clone
+    end
 
+    # Creates a new +Clipboard+
+    #
     def initialize
       clear
     end
 
+    # Add an element to the clipboard
+    #
+    # @param item [ElementBase]
+    #
     def add(item)
       @items.push(item)
+      self
     end
 
+    # Clears the clipboard
+    #
     def clear
       @items = []
+      self
     end
 
+    # Returns a concatenation of the pasting of each item on the clipboard
+    # @return [String]
+    #
     def paste
-      @items.map(&:paste).join("")
+      @items.map(&:paste).join('')
     end
 
+    # Iterates over each item on the clipboard
+    # @yield each item
+    # @return [Clipboard] self
+    #
     def each(&block)
-      @items.each do |item|
-        block.call(item)
+      if block_given?
+        @items.each do |item|
+          block.call(item)
+        end
       end
       self
     end
 
+    # Sorts the clipboard using the provided block
+    # @yield each item
+    # @return [Clipboard] self
+    #
     def sort_by!(&block)
       @items.sort_by!(&block)
+      self
     end
   end
 end

data/lib/kitchen/composite_chapter_element.rb

@@ -1,6 +1,15 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for a composite chapter
+  #
   class CompositeChapterElement < ElementBase
 
+    # Creates a new +CompositeChapterElement+
+    #
+    # @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,6 +17,11 @@ module Kitchen
             short_type: :composite_chapter)
     end
 
+    # Returns the title element (the one in the immediate children, not the one in the metadata)
+    #
+    # @raise [ElementNotFoundError] if no matching element is found
+    # @return [Element]
+    #
     def title
       # Get the title in the immediate children, not the one in the metadata.  Could use
       # CSS of ":not([data-type='metadata']) > [data-type='document-title'], [data-type='document-title']"
@@ -15,8 +29,13 @@ module Kitchen
       first!("./*[@data-type = 'document-title']")
     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'] == "composite-chapter"
+      node['data-type'] == 'composite-chapter'
     end
 
   end

data/lib/kitchen/composite_page_element.rb

@@ -1,6 +1,15 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for a composite page
+  #
   class CompositePageElement < ElementBase
 
+    # Creates a new +CompositePageElement+
+    #
+    # @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,6 +17,11 @@ module Kitchen
             short_type: :composite_page)
     end
 
+    # Returns the title element (the one in the immediate children, not the one in the metadata)
+    #
+    # @raise [ElementNotFoundError] if no matching element is found
+    # @return [Element]
+    #
     def title
       # Get the title in the immediate children, not the one in the metadata.  Could use
       # CSS of ":not([data-type='metadata']) > [data-type='document-title'], [data-type='document-title']"
@@ -15,12 +29,21 @@ module Kitchen
       first!("./*[@data-type = 'document-title']")
     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'] == "composite-page"
+      node['data-type'] == 'composite-page'
     end
 
+    # Returns true if this page is a book index
+    #
+    # @return [Boolean]
+    #
     def is_index?
-      has_class?("os-index-container")
+      has_class?('os-index-container')
     end
 
   end

data/lib/kitchen/composite_page_element_enumerator.rb

@@ -1,6 +1,14 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An enumerator for composite page elements
+  #
   class CompositePageElementEnumerator < ElementEnumeratorBase
 
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
     def self.factory
       ElementEnumeratorFactory.new(
         default_css_or_xpath: "div[data-type='composite-page']",

data/lib/kitchen/config.rb

@@ -1,20 +1,27 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # Kitchen configuration
+  #
   class Config
 
+    # Named CSS or XPath selectors
+    #
+    # @return [Selectors::Base]
+    #
     attr_reader :selectors
 
-    def self.new_from_file(file)
-      raise "NYI"
-    end
-
-    def self.new_default
-      new
+    # Creates a new config from a file (not implemented)
+    #
+    def self.new_from_file(_file)
+      raise 'NYI'
     end
 
+    # Creates a new Config instance
+    #
     def initialize(hash: {}, selectors: nil)
       @selectors = selectors || Kitchen::Selectors::Standard1.new
       @hash = hash
     end
-
   end
 end

data/lib/kitchen/counter.rb

@@ -1,6 +1,12 @@
+# frozen_string_literal: true
+
 module Kitchen
-  class Counter # hehe
+  # A simple counting object
+  #
+  # hehe
+  class Counter
 
+    # Creates a new +Counter+ instance
     def initialize
       reset
     end
@@ -13,7 +19,8 @@ module Kitchen
       @value += by
     end
 
-    # (see #increment)
+    # @!method inc
+    #   @see increment
     alias_method :inc, :increment
 
     # Returns the value of the counter

data/lib/kitchen/debug/print_recipe_error.rb

@@ -1,63 +1,82 @@
+# frozen_string_literal: true
+
 require 'rainbow'
 
 module Kitchen
+  # Debug helpers
   module Debug
-
     CONTEXT_LINES = 2
 
     def self.print_recipe_error(error:, source_location:, document:)
-      error_location = error.backtrace.detect do |entry|
-        entry.start_with?(source_location) || entry.match?(/kitchen\/lib\/kitchen\/directions/)
-      end
+      print_error_message(error)
 
-      error_filename, error_line_number = error_location.match(/(.*):(\d+):/)[1..2]
-      error_line_number = error_line_number.to_i
+      error_line_number, error_filename = get_error_location(error, source_location)
+      print_file_line_with_context(error_line_number, error_filename)
 
-      puts "The recipe has an error: " + Rainbow(error.message).bright
-      puts "at or near the following #{Rainbow('highlighted').red} line"
       puts "\n"
-      puts "-----+ #{Rainbow(error_filename).bright} -----"
 
-      line_numbers_before = (error_line_number-CONTEXT_LINES..error_line_number-1)
-      line_numbers_after  = (error_line_number+1..error_line_number+CONTEXT_LINES)
+      print_specific_help_line(error)
+      print_line_in_document_where_error_occurred(document)
+      print_backtrace_info(error)
+    end
 
-      File.readlines(error_filename).each.with_index do |line, line_index|
-        line_number = line_index + 1
+    def self.verbose?
+      !ENV['VERBOSE'].nil?
+    end
 
-        if line_numbers_before.include?(line_number) ||
-           line_numbers_after.include?(line_number)
-          print_file_line(line_number, line)
-        end
+    def self.print_error_message(error)
+      puts "The recipe has an error: #{Rainbow(error.message).bright}"
+    end
 
-        if line_number == error_line_number
-          print_file_line(line_number, Rainbow(line.chomp).red)
-        end
+    def self.print_backtrace_info(error)
+      if verbose?
+        puts "Full backtrace:\n"
+        puts(error.backtrace.map { |line| Rainbow(line).blue })
+      else
+        puts 'Full backtrace suppressed; enable by setting the VERBOSE env variable to something'
       end
+    end
 
+    def self.print_line_in_document_where_error_occurred(document)
+      current_node = document&.location&.raw
+      return unless current_node
+
+      puts "Encountered on line #{Rainbow(current_node.line).red} in the input document on element:"
+      puts current_node.dup.tap { |node| node.inner_html = '...' if node.inner_html != '' }.to_s
       puts "\n"
+    end
 
-      print_specific_help_line(error)
+    def self.print_file_line_with_context(line_number, filename)
+      puts "at or near the following #{Rainbow('highlighted').red} line"
+      puts "\n"
+      puts "-----+ #{Rainbow(filename).bright} -----"
 
-      current_node = document.location&.raw
+      line_numbers_before = (line_number - CONTEXT_LINES..line_number - 1)
+      line_numbers_after  = (line_number + 1..line_number + CONTEXT_LINES)
 
-      if current_node
-        puts "Encountered on line #{Rainbow(current_node.line).red} in the input document on element:"
-        puts current_node.dup.tap{|node| node.inner_html="..." if node.inner_html != ""}.to_s
-        puts "\n"
-      end
+      File.readlines(filename).each.with_index do |line, line_index|
+        current_line_number = line_index + 1
 
-      if ENV['VERBOSE']
-        puts "Full backtrace:\n"
-        puts error.backtrace.map{|line| Rainbow(line).blue}
-      else
-        puts "Full backtrace suppressed (enable by setting the VERBOSE environment variable to something)"
+        if line_numbers_before.include?(current_line_number) ||
+           line_numbers_after.include?(current_line_number)
+          print_file_line(current_line_number, line)
+        elsif current_line_number == line_number
+          print_file_line(current_line_number, Rainbow(line.chomp).red)
+        end
       end
     end
 
-    protected
+    def self.get_error_location(error, source_location)
+      error_location = error.backtrace.detect do |entry|
+        entry.start_with?(source_location) || entry.match?(/kitchen\/lib\/kitchen\/directions/)
+      end
+
+      error_filename, error_line_number = error_location.match(/(.*):(\d+):/)[1..2]
+      [error_line_number.to_i, error_filename]
+    end
 
     def self.print_file_line(line_number, line)
-      puts "#{"%5s" % line_number}| #{line}"
+      puts "#{format('%5s', line_number)}| #{line}"
     end
 
     def self.print_specific_help_line(error)
@@ -75,6 +94,5 @@ module Kitchen
       #   puts "\n"
       # end
     end
-
   end
 end

data/lib/kitchen/directions/.rubocop.yml

@@ -0,0 +1,22 @@
+inherit_from: ../../../.rubocop.yml
+
+# Directions are supposed to be a big list of steps, so don't let Rubocop penalize
+# us for that
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false # module names here are pretty clear

data/lib/kitchen/directions/bake_appendix.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 module Kitchen
   module Directions
     module BakeAppendix
-
       def self.v1(page:, number:)
         title = page.title
-        title.name = "h1"
+        title.name = 'h1'
         title.replace_children(with:
           <<~HTML
             <span class="os-part-text">#{I18n.t(:appendix)} </span>
@@ -15,12 +16,11 @@ module Kitchen
         )
 
         # Make a section with data-depth of X have a header level of X+1
-        page.search("section").each do |section|
+        page.search('section').each do |section|
           title = section.first!("[data-type='title']")
           title.name = "h#{section['data-depth'].to_i + 1}"
         end
       end
-
     end
   end
 end

data/lib/kitchen/directions/bake_chapter_glossary.rb

@@ -1,18 +1,22 @@
+# frozen_string_literal: true
+
 module Kitchen
   module Directions
+    # Bake directons for eoc glossary
+    #
     module BakeChapterGlossary
-
       def self.v1(chapter:, metadata_source:)
-        metadata_elements = metadata_source.search(%w(.authors .publishers .print-style
-                                                      .permissions [data-type='subject'])).copy
+        metadata_elements = metadata_source.children_to_keep.copy
 
-        definitions = chapter.glossaries.search("dl").cut
+        definitions = chapter.glossaries.search('dl').cut
         definitions.sort_by! do |definition|
-          [definition.first("dt").text.downcase, definition.first("dd").text.downcase]
+          [definition.first('dt').text.downcase, definition.first('dd').text.downcase]
         end
 
         chapter.glossaries.trash
 
+        return if definitions.none?
+
         chapter.append(child:
           <<~HTML
             <div class="os-eoc os-glossary-container" data-type="composite-page" data-uuid-key="glossary">
@@ -26,9 +30,8 @@ module Kitchen
               #{definitions.paste}
             </div>
           HTML
-        ) unless definitions.none?
+        )
       end
-
     end
   end
 end