openstax_kitchen 1.0.0 → 4.0.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,7 +33,13 @@ 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

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

data/lib/kitchen/patches/string.rb

@@ -1,4 +1,12 @@
+# frozen_string_literal: true
+
+# Monkey patches for +String+
+#
 class String
+  # Downcases the first letter of self, returning a new string
+  #
+  # @return [String]
+  #
   def uncapitalize
     sub(/^[A-Z]/, &:downcase)
   end

data/lib/kitchen/recipe.rb

@@ -1,9 +1,28 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An object that yields a +Document+ for modification (those modifications are
+  # the "recipe")
+  #
   class Recipe
 
+    # The document the recipe makes available for modification
+    # @return [Document]
     attr_reader :document
+
+    # The file location of the recipe
+    # @return [String]
     attr_reader :source_location
 
+    # An I18n backend specific to this recipe, may be nil
+    # @return [I18n::Backend::Simple, nil]
+    attr_reader :my_i18n_backend
+
+    # Sets the document so the recipe can yield it for modification
+    #
+    # @param document [Document] the document to modify
+    # @raise [StandardError] if not passed supported document type
+    #
     def document=(document)
       @document =
         case document
@@ -16,57 +35,75 @@ module Kitchen
 
     # Make a new Recipe
     #
+    # @param locales_dir [String, nil] the absolute path to a folder containing recipe-specific
+    #   I18n translations.  If not provided, Kitchen will look for a `locales` directory in the
+    #   same directory as the recipe source.  Recipe-specific translations override those in
+    #   Kitchen.  If no recipe-specific locales directory exists, Kitchen will just use its default
+    #   translations.
+    # @yield A block for defining the steps of the recipe
     # @yieldparam doc [Document] an object representing an XML document
     #
-    def initialize(&block)
+    def initialize(locales_dir: nil, &block)
+      raise(RecipeError, 'Recipes must be initialized with a block') unless block_given?
+
       @source_location = block.source_location[0]
       @block = block
-    end
 
-    def node!
-      node || raise("The recipe's node has not been set")
+      load_my_i18n_backend(locales_dir)
     end
 
+    # Executes the block given to +Recipe.new+ on the document.  Aka, does the baking.
+    #
     def bake
-      begin
+      with_my_locales do
         @block.to_proc.call(document)
-      rescue RecipeError => ee
-        print_recipe_error_and_exit(ee)
-      rescue ArgumentError => ee
-        if if_any_stack_file_matches_source_location?(ee)
-          print_recipe_error_and_exit(ee)
-        else
-          raise
-        end
-      rescue NoMethodError => ee
-        if if_any_stack_file_matches_source_location?(ee)
-          print_recipe_error_and_exit(ee)
-        else
-          raise
-        end
-      rescue NameError => ee
-        if if_stack_starts_with_source_location?(ee)
-          print_recipe_error_and_exit(ee)
-        else
-          raise
-        end
-      rescue ElementNotFoundError => ee
-        print_recipe_error_and_exit(ee)
-      rescue Nokogiri::CSS::SyntaxError => ee
-        print_recipe_error_and_exit(ee)
       end
+    rescue RecipeError, ElementNotFoundError, Nokogiri::CSS::SyntaxError => e
+      print_recipe_error_and_exit(e)
+    rescue ArgumentError, NoMethodError => e
+      raise unless any_stack_file_matches_source_location?(e)
+
+      print_recipe_error_and_exit(e)
+    rescue NameError => e
+      raise unless stack_starts_with_source_location?(e)
+
+      print_recipe_error_and_exit(e)
     end
 
     protected
 
-    def if_stack_starts_with_source_location?(error)
+    def stack_starts_with_source_location?(error)
       error.backtrace.first.start_with?(source_location)
     end
 
-    def if_any_stack_file_matches_source_location?(error)
-      error.backtrace.any? {|entry| entry.start_with?(@source_location)}
+    def any_stack_file_matches_source_location?(error)
+      error.backtrace.any? { |entry| entry.start_with?(@source_location) }
+    end
+
+    def load_my_i18n_backend(locales_dir)
+      locales_dir ||= begin
+        guessed_locales_dir = "#{File.dirname(@source_location)}/locales"
+        File.directory?(guessed_locales_dir) ? guessed_locales_dir : nil
+      end
+
+      return unless locales_dir
+
+      @my_i18n_backend = I18n::Backend::Simple.new
+      @my_i18n_backend.load_translations(Dir[File.expand_path("#{locales_dir}/*.yml")])
+    end
+
+    def with_my_locales
+      original_i18n_backend = I18n.backend
+      I18n.backend = I18n::Backend::Chain.new(my_i18n_backend, original_i18n_backend)
+      yield
+    ensure
+      I18n.backend = original_i18n_backend
     end
 
+    # Print the given recipe error and do a process exit
+    #
+    # @param error [RecipeError] the error
+    #
     def print_recipe_error_and_exit(error)
       Kitchen::Debug.print_recipe_error(error: error,
                                         source_location: source_location,