openstax_kitchen 2.0.0 → 4.1.0

data/lib/kitchen/book_element_enumerator.rb

@@ -1,4 +1,8 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An enumerator for book elements
+  #
   class BookElementEnumerator < ElementEnumeratorBase
     # Unsure if this class is needed; there is only one book element per document
   end

data/lib/kitchen/book_recipe.rb

@@ -1,17 +1,31 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # A specialized +Recipe+ that yields a +BookDocument+ instead of a plain
+  # +Document+
+  #
   class BookRecipe < Recipe
 
+    # The book's short name
+    #
+    # @return [Symbol]
+    #
     attr_reader :book_short_name
 
     # Make a new BookRecipe
     #
+    # @param book_short_name [Symbol, String] the book's short name
     # @yieldparam doc [BookDocument] an object representing an XML document
     #
     def initialize(book_short_name: :not_set, &block)
-      @book_short_name = book_short_name
+      @book_short_name = book_short_name.to_sym
       super(&block)
     end
 
+    # Overrides +document=+ to ensure a +BookDocument+ is stored
+    #
+    # @param document [Document, Nokogiri::XML::Document] the document
+    #
     def document=(document)
       super(document)
       @document = Kitchen::BookDocument.new(

data/lib/kitchen/chapter_element.rb

@@ -1,34 +1,71 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for a chapter
+  #
   class ChapterElement < ElementBase
 
+    # Creates a new +ChapterElement+
+    #
+    # @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,
-            enumerator_class: ChapterElementEnumerator,
-            short_type: :chapter)
+            enumerator_class: ChapterElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :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']"
+      # CSS of ":not([data-type='metadata']) >
+      #       [data-type='document-title'], [data-type='document-title']"
       # but xpath is shorter
       first!("./*[@data-type = 'document-title']")
     end
 
+    # Returns the introduction page
+    #
+    # @return [Element, nil]
+    #
     def introduction_page
       pages('.introduction').first
     end
 
+    # Returns an enumerator for the glossaries
+    #
+    # @return [ElementEnumerator]
+    #
     def glossaries
       search("div[data-type='glossary']")
     end
 
+    # Returns an enumerator for the key equations
+    #
+    # @return [ElementEnumerator]
+    #
     def key_equations
-      search("section.key-equations")
+      search('section.key-equations')
     end
 
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == "chapter"
+    # Returns an enumerator for the abstracts
+    #
+    # @return [ElementEnumerator]
+    #
+    def abstracts
+      search('[data-type="abstract"]')
     end
 
   end

data/lib/kitchen/chapter_element_enumerator.rb

@@ -1,9 +1,17 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An enumerator for chapter elements
+  #
   class ChapterElementEnumerator < ElementEnumeratorBase
 
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
     def self.factory
       ElementEnumeratorFactory.new(
-        default_css_or_xpath: "div[data-type='chapter']", # TODO element.document.selectors.chapter
+        default_css_or_xpath: Selector.named(:chapter),
         sub_element_class: ChapterElement,
         enumerator_class: self
       )

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,13 +1,32 @@
+# 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,
-            enumerator_class: ElementEnumerator,
-            short_type: :composite_chapter)
+            enumerator_class: ElementEnumerator)
+    end
+
+    # Returns short type
+    #
+    def self.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,9 +34,5 @@ module Kitchen
       first!("./*[@data-type = 'document-title']")
     end
 
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == "composite-chapter"
-    end
-
   end
 end

data/lib/kitchen/composite_page_element.rb

@@ -1,26 +1,54 @@
+# 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,
-            enumerator_class: CompositePageElementEnumerator,
-            short_type: :composite_page)
+            enumerator_class: CompositePageElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.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']"
       # but xpath is shorter
-      first!("./*[@data-type = 'document-title']")
+      first!("./*[@data-type = 'document-title' or @data-type = 'title']")
     end
 
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == "composite-page"
+    # Returns true if this page is a book index
+    #
+    # @return [Boolean]
+    #
+    def is_index?
+      has_class?('os-index-container')
     end
 
-    def is_index?
-      has_class?("os-index-container")
+    # Returns true if this page is a book reference
+    #
+    # @return [Boolean]
+    #
+    def is_reference?
+      has_class?('os-reference-container')
     end
 
   end

data/lib/kitchen/composite_page_element_enumerator.rb

@@ -1,9 +1,17 @@
+# 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']",
+        default_css_or_xpath: Selector.named(:composite_page),
         sub_element_class: CompositePageElement,
         enumerator_class: self
       )

data/lib/kitchen/config.rb

@@ -1,20 +1,34 @@
+# 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
+    # @!attribute [rw] enable_all_namespaces
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :enable_all_namespaces
 
-    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
+      @enable_all_namespaces = hash[:enable_all_namespaces] || true
       @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