openstax_kitchen 2.0.0 → 4.1.0

data/lib/kitchen/note_element_enumerator.rb

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

data/lib/kitchen/oven.rb

@@ -1,11 +1,18 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # A class for baking documents according to the instructions in recipes
+  #
   class Oven
 
-    def self.bake(input_file:,
-                  config_file: nil,
-                  recipes:,
-                  output_file:)
-
+    # Bakes an input file using a recipe to produce an output file
+    #
+    # @param input_file [String] the path to the input file
+    # @param config_file [String] the path to the configuration file
+    # @param recipes [Array<Recipe>] an array of recipes with which to bake the document
+    # @param output_file [String] the path to the output file
+    #
+    def self.bake(input_file:, recipes:, output_file:, config_file: nil)
       profile = BakeProfile.new
       profile.started!
 
@@ -27,32 +34,76 @@ module Kitchen
       end
       profile.baked!
 
-      File.open(output_file, "w") do |f|
-        f.write doc.to_xhtml(indent:2)
+      File.open(output_file, 'w') do |f|
+        f.write doc.to_xhtml(indent: 2)
       end
       profile.written!
 
       profile
     end
 
+    # Stats on baking
+    #
     class BakeProfile
+      # Record that baking has started
       def started!; @started_at = Time.now; end
+
+      # Record that the input file has been opened
       def opened!;  @opened_at = Time.now;  end
+
+      # Record that the input file has been parsed
       def parsed!;  @parsed_at = Time.now;  end
+
+      # Record that the input file has been baked
       def baked!;   @baked_at = Time.now;   end
+
+      # Record that the output file has been written
       def written!; @written_at = Time.now; end
 
-      def open_seconds;  @opened_at  - @started_at; end
-      def parse_seconds; @parsed_at  - @opened_at;  end
-      def bake_seconds;  @baked_at   - @parsed_at;  end
-      def write_seconds; @written_at - @baked_at;   end
+      # Return the number of seconds it took to open the input file or nil if this
+      # info isn't available.
+      # @return [Float, nil]
+      def open_seconds
+        @opened_at - @started_at
+      rescue NoMethodError
+        nil
+      end
+
+      # Return the number of seconds it took to parse the input file after opening or
+      # nil if this info isn't available.
+      # @return [Float, nil]
+      def parse_seconds
+        @parsed_at - @opened_at
+      rescue NoMethodError
+        nil
+      end
+
+      # Return the number of seconds it took to bake the parsed file or nil if this
+      # info isn't available.
+      # @return [Float, nil]
+      def bake_seconds
+        @baked_at - @parsed_at
+      rescue NoMethodError
+        nil
+      end
+
+      # Return the number of seconds it took to write the baked file or nil if this
+      # info isn't available.
+      # @return [Float, nil]
+      def write_seconds
+        @written_at - @baked_at
+      rescue NoMethodError
+        nil
+      end
 
+      # Return the profile stats as a string
+      # @return [String]
       def to_s
         <<~STRING
-          Open:  #{open_seconds} s
-          Parse: #{parse_seconds} s
-          Bake:  #{bake_seconds} s
-          Write: #{write_seconds} s
+          Open:  #{open_seconds || '??'} s
+          Parse: #{parse_seconds || '??'} s
+          Bake:  #{bake_seconds || '??'} s
+          Write: #{write_seconds || '??'} s
         STRING
       end
     end

data/lib/kitchen/page_element.rb

@@ -1,50 +1,120 @@
+# 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,
-            enumerator_class: PageElementEnumerator,
-            short_type: :page)
+            enumerator_class: PageElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.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 the title's text regardless of whether the title has been baked
+    #
+    # @return [String]
+    #
+    def title_text
+      title.children.one? ? title.text : title.first('.os-text').text
+    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")
+      first!('section.exercises')
     end
 
-    def exercises_section
-      search("")
+    # Returns the key concepts
+    #
+    # @return [Element]
+    #
+    def key_concepts
+      search('section.key-concepts')
     end
 
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == "page"
+    # Returns the free response questions
+    #
+    # @return [Element]
+    #
+    def free_response
+      search('section.free-response')
     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: Selector.named(:page),
         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,10 +33,56 @@ 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
+
+      def quick_matches?(selector)
+        self.class.selector_to_css_nodes(selector).any? { |css_node| matches_css_node?(css_node) }
+      end
+
+      def classes
+        self[:class]&.split || []
+      end
+
+      def self.selector_to_css_nodes(selector)
+        # No need to parse the same selector more than once.
+        @parsed_selectors ||= {}
+        @parsed_selectors[selector] ||= Nokogiri::CSS::Parser.new.parse(selector)
+      end
+
+      protected
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def matches_css_node?(css_node)
+        case css_node.type
+        when :CONDITIONAL_SELECTOR
+          css_node.value.all? { |inner_css_node| matches_css_node?(inner_css_node) }
+        when :ELEMENT_NAME
+          css_node.value == ['*'] || css_node.value.include?(name)
+        when :CLASS_CONDITION
+          (css_node.value & classes).any?
+        when :ATTRIBUTE_CONDITION
+          attribute, operator, value = css_node.value
+
+          raise "Unknown attribute condition operator in #{css_node}" if operator != :equal
+
+          attribute_name = attribute.value
+          raise "More attribute names than expected, #{attribute_name}" if attribute_name.many?
+
+          self[attribute_name.first] == value.gsub('"', '').gsub("'", '')
+        else
+          raise "Unknown Nokogiri::CSS:Node type in #{css_node}"
+        end
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
     end
   end
 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