openstax_kitchen 2.0.0 → 4.1.0

data/lib/kitchen/element_factory.rb

@@ -1,32 +1,47 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # Builds Elements from Nokogiri Nodes
+  #
   class ElementFactory
 
     ELEMENT_CLASSES = ElementBase.descendants
 
-    def self.specific_element_class_for_node(node)
-      ELEMENT_CLASSES.find do |klass|
-        klass.is_the_element_class_for?(node)
-      end || Element
-    end
-
+    # Builds a new concrete subclass of ElementBase for the provided node.
+    #
+    # @param node [Nokogiri::XML::Node] the node to wrap in an element
+    # @param document [Document] the document
+    # @param element_class [ElementBase] actually a subclass of +ElementBase+ to
+    #   use when wrapping the node.
+    # @param default_short_type [Symbol, String] if we are making an instance
+    #   of an element class where we know the short_type we'll use that; otherwise
+    #   we'll make an Element instance and use this argument as the short_type.
+    # @param detect_element_class [Boolean] if true and +element_class+ is not given,
+    #   attempts to detect the element class from the node
+    # @return [ElementBase] actually a subclass of +ElementBase+
+    #
     def self.build_from_node(node:,
                              document:,
                              element_class: nil,
                              default_short_type: nil,
                              detect_element_class: false)
-      element_class ||= detect_element_class ?
-                        specific_element_class_for_node(node) :
-                        Element
+      element_class ||= detect_element_class ? find_element_class(node, document.config) : Element
 
       if element_class == Element
         element_class.new(node: node,
-                              document: document,
-                              short_type: default_short_type)
+                          document: document,
+                          short_type: default_short_type)
       else
         element_class.new(node: node,
-                              document: document)
+                          document: document)
       end
     end
 
+    def self.find_element_class(node, config)
+      ELEMENT_CLASSES.find do |klass|
+        klass.is_the_element_class_for?(node, config: config)
+      end || Element
+    end
+
   end
 end

data/lib/kitchen/errors.rb

@@ -1,4 +1,9 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # Raised likely due to a problem in the recipe, not in Kitchen
   class RecipeError < StandardError; end
+
+  # Raised when an element not found
   class ElementNotFoundError < StandardError; end
 end

data/lib/kitchen/example_element.rb

@@ -1,19 +1,34 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for an example
+  #
   class ExampleElement < ElementBase
 
+    # Creates a new +ExampleElement+
+    #
+    # @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: ExampleElementEnumerator,
-            short_type: :example)
+            enumerator_class: ExampleElementEnumerator)
     end
 
-    def titles
-      search("span[data-type='title']")
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :example
     end
 
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == "example"
+    # Returns the an enumerator for titles.
+    #
+    # @return [ElementEnumerator]
+    #
+    def titles
+      search("span[data-type='title']")
     end
 
   end

data/lib/kitchen/example_element_enumerator.rb

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

data/lib/kitchen/exercise_element.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An element for an example
+  #
+  class ExerciseElement < ElementBase
+
+    # Creates a new +ExerciseElement+
+    #
+    # @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: ExerciseElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :exercise
+    end
+
+    # Returns the enumerator for problem.
+    #
+    # @return ElementEnumerator
+    #
+    def problem
+      first("[data-type='problem']")
+    end
+
+    # Returns the enumerator for solution.
+    #
+    # @return ElementEnumerator
+    #
+    def solution
+      first("[data-type='solution']")
+    end
+  end
+end

data/lib/kitchen/exercise_element_enumerator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An enumerator for example elements
+  #
+  class ExerciseElementEnumerator < ElementEnumeratorBase
+
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
+    def self.factory
+      ElementEnumeratorFactory.new(
+        default_css_or_xpath: Selector.named(:exercise),
+        sub_element_class: ExerciseElement,
+        enumerator_class: self
+      )
+    end
+
+  end
+end

data/lib/kitchen/figure_element.rb

@@ -1,19 +1,50 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for a figure
+  #
   class FigureElement < ElementBase
 
+    # Creates a new +FigureElement+
+    #
+    # @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: FigureElementEnumerator,
-            short_type: :figure)
+            enumerator_class: FigureElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :figure
     end
 
+    # Returns the caption element
+    #
+    # @return [Element, nil]
+    #
     def caption
-      first("figcaption")
+      first('figcaption')
+    end
+
+    # Returns the Figure Title
+    #
+    # @return [Element, nil]
+    #
+    def title
+      first("div[data-type='title']")
     end
 
-    def self.is_the_element_class_for?(node)
-      node.name == "figure"
+    # Returns true if the figure is a child of another figure
+    #
+    # @return [Boolean]
+    #
+    def subfigure?
+      parent.name == 'figure'
     end
 
   end

data/lib/kitchen/figure_element_enumerator.rb

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

data/lib/kitchen/metadata_element.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An element for metadata
+  #
+  class MetadataElement < ElementBase
+    # Creates a new +MetadataElement+
+    #
+    # @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: MetadataElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :metadata
+    end
+
+    # Returns set of selected data elements
+    #
+    # @return [ElementEnumerator]
+    #
+    def children_to_keep
+      search(%w([data-type='revised'] .authors .publishers .print-style .permissions
+                [data-type='subject']))
+    end
+  end
+end

data/lib/kitchen/metadata_element_enumerator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An enumerator for metadata elements
+  #
+  class MetadataElementEnumerator < ElementEnumeratorBase
+
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
+    def self.factory
+      ElementEnumeratorFactory.new(
+        default_css_or_xpath: Selector.named(:metadata),
+        sub_element_class: MetadataElement,
+        enumerator_class: self
+      )
+    end
+
+  end
+end

data/lib/kitchen/mixins/block_error_if.rb

@@ -1,19 +1,39 @@
+# frozen_string_literal: true
+
 module Kitchen
   module Mixins
+    # A mixin for including the block_error_if method
+    #
+    # @example
+    #   class SomeClass
+    #     include Mixins::BlockErrorIf
+    #
+    #     def foo
+    #       block_error_if(block_given?)
+    #     end
+    #   end
     module BlockErrorIf
-
+      # All Ruby methods can take blocks, but not all of them use the block.  If a block is given but
+      # not expected, we want to raise an error to help the developer figure out why their block isn't
+      # doing what they expect.  The method does some work to figure out where the block was errantly
+      # given to help the developer find the errant line of code.
+      #
+      # @param block_given [Boolean] true if block was given
+      # @raise [RecipeError] if a block was given
+      #
       def block_error_if(block_given)
+        return unless block_given
+
         calling_method = begin
           this_method_location_index = caller_locations.find_index do |location|
-            location.label == "block_error_if"
+            location.label == 'block_error_if'
           end
 
           caller_locations[(this_method_location_index || -1) + 1].label
         end
 
-        raise(RecipeError, "The `#{calling_method}` method does not take a block argument") if block_given
+        raise(RecipeError, "The `#{calling_method}` method does not take a block")
       end
-
     end
   end
 end

data/lib/kitchen/note_element.rb

@@ -1,43 +1,71 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for a note
+  #
   class NoteElement < ElementBase
 
-    TITLE_TRANSLATION_KEYS = %w(
-      link-to-learning
-      everyday-life
-      sciences-interconnect
-      chemist-portrait
-    )
-
+    # Creates a new +NoteElement+
+    #
+    # @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: NoteElementEnumerator,
-            short_type: :note)
+            enumerator_class: NoteElementEnumerator)
     end
 
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :note
+    end
+
+    # Returns the note's title element
+    #
+    # @return [Element, nil]
+    #
     def title
       block_error_if(block_given?)
       first("[data-type='title']")
     end
 
+    # Returns true if the note's title is autogenerated
+    #
+    # @return [Boolean]
+    #
     def indicates_autogenerated_title?
-      translation_key_in(TITLE_TRANSLATION_KEYS).present?
+      detected_note_title_key != 0 && detected_note_title_key.present?
     end
 
+    # Get the autogenerated title for this note
+    #
+    # @return [String]
+    #
     def autogenerated_title
-      translation_key = translation_key_in(TITLE_TRANSLATION_KEYS)
-      I18n.t(:"notes.#{document.short_name}.#{translation_key}", default: :"notes.#{translation_key}")
+      if indicates_autogenerated_title?
+        I18n.t(:"notes.#{detected_note_title_key}")
+      else
+        "unknown title for note with classes #{classes}"
+      end
     end
 
-    def translation_key_in(possible_translation_keys)
-      keys = possible_translation_keys & classes
-      raise("too many translation keys: #{keys.join(', ')}") if keys.many?
-      keys.first
-    end
+    protected
 
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == "note"
-    end
+    def detected_note_title_key
+      @detected_note_title_key ||= begin
+        return 0 if classes.empty? || !I18n.t('.').key?(:notes)
+
+        possible_keys = I18n.t(:notes).keys.map(&:to_s)
+        keys = possible_keys & classes
 
+        raise("too many translation keys: #{keys.join(', ')}") if keys.many?
+        return 0 if keys.empty?
+
+        keys.first
+      end
+    end
   end
 end