openstax_kitchen 2.0.0 → 3.0.0

data/Rakefile

@@ -1,6 +1,8 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "openstax_kitchen"
+require 'bundler/setup'
+require 'openstax_kitchen'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "openstax_kitchen"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/docker/Dockerfile

@@ -0,0 +1,36 @@
+FROM ruby:2.6-slim
+
+ARG bundler_version
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    git \
+    vim \
+    openssh-server \
+    build-essential \
+    wget \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install a quick colorized prompt and turn on ls coloring
+RUN git clone https://github.com/nojhan/liquidprompt.git ~/liquidprompt && \
+    echo '[[ $- = *i* ]] && source ~/liquidprompt/liquidprompt' >>~/.bashrc && \
+    mkdir -p ~/.config && \
+    echo 'export LP_HOSTNAME_ALWAYS=1' >>~/.config/liquidpromptrc && \
+    echo 'export LP_USER_ALWAYS=-1' >>~/.config/liquidpromptrc && \
+    sed -i "/color=auto/"' s/# //' ~/.bashrc && \
+    sed -i "/alias ls/,/lA/"' s/# //' ~/.bashrc
+
+# VSCode Live Share libraries
+RUN wget -O ~/vsls-reqs https://aka.ms/vsls-linux-prereq-script && chmod +x ~/vsls-reqs && ~/vsls-reqs
+
+WORKDIR /code
+COPY . /code/
+
+RUN gem install bundler --no-document --version $bundler_version && \
+    gem install solargraph && \
+    gem install lefthook && \
+    bundle config set no-cache 'true' && \
+    bundle config set silence_root_warning 'true' && \
+    bundle install && \
+    echo "Generating YARD documentation for gems (this can be slow)..." && \
+    bundle exec yard gems --quiet

data/docker/Dockerfile.ci

@@ -0,0 +1,10 @@
+# Use non-slim to have git and build tools installed (faster for lots of runs
+# on CI)
+FROM ruby:2.6
+
+ARG bundler_version
+
+RUN gem install bundler --no-document --version $bundler_version
+
+WORKDIR /code
+COPY . /code/

data/docker/bash

@@ -1 +1,5 @@
-docker-compose exec app bash
+#!/usr/bin/env bash
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+$DIR/run /bin/bash

data/docker/build

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+if [ "$1" == "--ci" ]; then SUFFIX=".ci"; else SUFFIX=""; fi
+
+docker build -f $DIR/Dockerfile$SUFFIX \
+             -t openstax/kitchen$SUFFIX:latest \
+             --build-arg bundler_version=2.2.4 \
+             $DIR/..

data/docker/ci

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+# See https://docs.codecov.io/docs/testing-with-docker, also note that it is
+# critical to set CI=true because codecov-ruby won't detect GitHub Actions
+# without it per:
+# https://github.com/codecov/codecov-ruby/blob/484767f1c3d7992a9d7fedd6dc72d35a80d04f70/lib/codecov.rb#L68-L69
+
+docker run $CI_ENV \
+           -e ENABLE_CODECOV=1 -e CI=true \
+           -v $DIR/..:/code \
+           -v vendor/bundle \
+           -w /code \
+           openstax/kitchen.ci:latest \
+           /bin/bash -c "bundle config path vendor/bundle; bundle install; bundle exec rspec"

data/docker/run

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+docker run -it \
+           -v $DIR/..:/code \
+           -w /code \
+           openstax/kitchen:latest \
+           "$@"

data/docker/tag_and_push_latest

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+TAG="docker tag openstax/kitchen:latest openstax/kitchen:$1"
+PUSH="docker push openstax/kitchen:$1"
+
+echo "About to run the following:"
+echo $TAG
+echo $PUSH
+
+read -p "Are you sure? (Y/n) " -r
+echo    # (optional) move to a new line
+if [[ $REPLY =~ ^[Yy]$ ]]
+then
+    $TAG
+    echo Tagged!
+    $PUSH
+fi

data/lefthook.yml

@@ -0,0 +1,6 @@
+pre-push:
+  commands:
+    rubocop:
+      files: git diff --name-only main
+      glob: "*.rb"
+      run: bundle exec rubocop {files} --disable-pending-cops

data/lib/kitchen/ancestor.rb

@@ -1,28 +1,65 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # A wrapper for an element representing an ancestor (up the DOM tree) of another
+  # element; keeps track of the number of descendants it has of a particular type
+  #
   class Ancestor
 
-    attr_accessor :type
+    # The type, e.g. +:page+, +:term+
+    # @return [Symbol] the type
+    #
+    attr_reader :type
+
+    # The ancestor element
+    # @return [ElementBase] the ancestor element
+    #
     attr_accessor :element
 
+    # Create a new Ancestor
+    #
+    # @param element [ElementBase] the ancestor element
+    #
     def initialize(element)
       @element = element
       @type = element.short_type
       @descendant_counts = {}
     end
 
+    # Adds 1 to the descendant count for the given type
+    #
+    # @param descendant_type [String, Symbol] the descendent's type
+    #
     def increment_descendant_count(descendant_type)
       @descendant_counts[descendant_type.to_sym] = get_descendant_count(descendant_type) + 1
     end
 
+    # Decreases the descendant count for the given type by some amount
+    #
+    # @param descendant_type [String, Symbol] the descendent's type
+    # @param by [Integer] the amount by which to decrement
+    # @raise [RangeError] if descendant count is a negative number
+    #
     def decrement_descendant_count(descendant_type, by: 1)
+      raise(RangeError, 'An element cannot have negative descendants') \
+        if (get_descendant_count(descendant_type) - by).negative?
+
       @descendant_counts[descendant_type.to_sym] = get_descendant_count(descendant_type) - by
     end
 
+    # Returns the descendant count for the given type
+    #
+    # @param descendant_type [String, Symbol] the descendent's type
+    # @return [Integer] the count
+    #
     def get_descendant_count(descendant_type)
       @descendant_counts[descendant_type.to_sym] || 0
     end
 
+    # Makes a new Ancestor around the same element, with new counts
+    #
     def clone
+      # @todo Delete later if not used
       Ancestor.new(element)
     end
 

data/lib/kitchen/book_document.rb

@@ -1,17 +1,35 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # A specialized form of +Document+ for our books.
+  #
   class BookDocument < Document
 
+    # This book's short name, used to look up translations, etc.
+    # @return [Symbol] the name
+    #
     attr_reader :short_name
 
+    # Creates a new BookDocument
+    #
+    # @param document [Document, Nokogiri::XML::Document] the underlying document;
+    #   if a +Document+ it is converted to a +Nokogiri::XML::Document+
+    # @param short_name [Symbol, String] the book's short name
+    # @param config [Config] the book's configuration
+    #
     def initialize(document:, short_name: :not_set, config: nil)
-      @short_name = short_name
+      @short_name = short_name.to_sym
 
       super(nokogiri_document: document.is_a?(Document) ? document.raw : document,
             config: config)
     end
 
+    # Returns the top-level +BookElement+ for this document
+    #
+    # @return [BookElement]
+    #
     def book
-      BookElement.new(node: nokogiri_document.search("html").first, document: self)
+      BookElement.new(node: nokogiri_document.search('html').first, document: self)
     end
 
   end

data/lib/kitchen/book_element.rb

@@ -1,6 +1,15 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for an entire book
+  #
   class BookElement < ElementBase
 
+    # Creates a new +BookElement+
+    #
+    # @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,16 +17,28 @@ module Kitchen
             short_type: :book)
     end
 
+    # Returns the "body" element
+    #
+    # @return [Element]
+    #
     def body
-      first!("body")
+      first!('body')
     end
 
+    # Returns the top metadata element
+    #
+    # @return [MetadataElement]
+    #
     def metadata
-      first!("div[data-type='metadata']")
+      metadatas.first
     end
 
+    # Returns the table of contents (toc) element
+    #
+    # @return [Element]
+    #
     def toc
-      first!("nav#toc")
+      first!('nav#toc')
     end
 
   end

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,6 +1,15 @@
+# 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,
@@ -8,27 +17,58 @@ module Kitchen
             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
+
+    # Returns an enumerator for the abstracts
+    #
+    # @return [ElementEnumerator]
+    #
+    def abstracts
+      search('[data-type="abstract"]')
     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'] == "chapter"
+      node['data-type'] == 'chapter'
     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: "div[data-type='chapter']", # TODO: element.document.selectors.chapter
         sub_element_class: ChapterElement,
         enumerator_class: self
       )