openstax_kitchen 2.0.0 → 3.0.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 ? specific_element_class_for_node(node) : 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.specific_element_class_for_node(node)
+      ELEMENT_CLASSES.find do |klass|
+        klass.is_the_element_class_for?(node)
+      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,6 +1,15 @@
+# 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,
@@ -8,12 +17,21 @@ module Kitchen
             short_type: :example)
     end
 
+    # Returns the an enumerator for titles.
+    #
+    # @return [ElementEnumerator]
+    #
     def titles
       search("span[data-type='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'] == "example"
+      node['data-type'] == 'example'
     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: "div[data-type='example']", # TODO: element.document.selectors.example
         sub_element_class: ExampleElement,
         enumerator_class: self
       )

data/lib/kitchen/figure_element.rb

@@ -1,6 +1,15 @@
+# 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,
@@ -8,12 +17,37 @@ module Kitchen
             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
+
+    # Returns true if the figure is a child of another figure
+    #
+    # @return [Boolean]
+    #
+    def subfigure?
+      parent.name == 'figure'
     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.name == "figure"
+      node.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: 'figure', # TODO: get from config?
         sub_element_class: FigureElement,
         enumerator_class: self
       )

data/lib/kitchen/metadata_element.rb

@@ -0,0 +1,28 @@
+# 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,
+            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: "div[data-type='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,13 +1,22 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for a note
+  #
   class NoteElement < ElementBase
 
-    TITLE_TRANSLATION_KEYS = %w(
+    TITLE_TRANSLATION_KEYS = %w[
       link-to-learning
       everyday-life
       sciences-interconnect
       chemist-portrait
-    )
+    ].freeze
 
+    # 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,
@@ -15,28 +24,49 @@ module Kitchen
             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?
     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}")
+      I18n.t(:"notes.#{document.short_name}.#{translation_key}",
+             default: :"notes.#{translation_key}")
     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'] == 'note'
+    end
+
+    protected
+
     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
 
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == "note"
+      keys.first
     end
 
   end

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: "div[data-type='note']", # TODO: get from config?
         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