openstax_kitchen 1.0.0 → 4.0.0

data/README.md

@@ -3,14 +3,16 @@
 [![Tests](https://github.com/openstax/kitchen/workflows/Tests/badge.svg)](https://github.com/openstax/kitchen/actions?query=workflow:Tests)
 [![Coverage Status](https://img.shields.io/codecov/c/github/openstax/kitchen.svg)](https://codecov.io/gh/openstax/kitchen)
 
-Kitchen lets you modify the structure and content of XML files.  You create a `Recipe` with instructions and `bake` it in the `Oven`
+Kitchen lets you modify the structure and content of XML files.  You create a `Recipe` with instructions and `bake` it in the `Oven`.
+
+[Full documentation at rubydoc.info](https://rubydoc.info/github/openstax/kitchen).
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'kitchen'
+gem 'openstax_kitchen'
 ```
 
 And then execute:
@@ -19,7 +21,7 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install kitchen
+    $ gem install openstax_kitchen
 
 ## Two Ways to Use Kitchen
 
@@ -32,7 +34,7 @@ We'll first talk about the generic way since those tools are also available in t
 Kitchen lets you modify the structure and content of XML files.  You create a `Recipe` and `bake` it in the `Oven`:
 
 ```ruby
-require "kitchen"
+require "openstax_kitchen"
 
 recipe = Kitchen::Recipe.new do |document|
   document.search("div.section").each do |element|
@@ -208,6 +210,13 @@ And we can wrap an element with another element:
 doc.search("span").first.wrap("<span class='other'>")
 ```
 
+or wrap an element's children:
+
+```ruby
+# <div><span>Hi</span></div> => <div><span><span class="other" data-type="foo">Hi</span></span></div>
+doc.search("span").first.wrap_children('span', class: 'other', data_type: 'foo')
+```
+
 ### Checking for elements
 
 You can see if an element contains an element matching a selector:
@@ -271,6 +280,31 @@ The CSS for these specific search methods is hidden away so you don't have to de
 doc.book.tables("$.unnumbered").cut
 ```
 
+Sometimes, it is difficult to setup a search using CSS.  In such cases, you can also pass `only` and `except` arguments to search methods, e.g.:
+
+```ruby
+doc.book.figures(except: :subfigure?)
+```
+
+`only` and `except` can be the names of methods (that return truthy/falsy values) on the element being iterated over, as shown above, or they can be lambdas or procs as shown here:
+
+```ruby
+doc.book.figures(only: ->(fig) { fig.children.count == 2 })
+```
+
+Obviously this is a somewhat contrived example, but the idea is that by passing a callable you can do complex searches.
+
+### Overriding Default Book-Oriented Selectors
+
+Book-oriented methods like `book.pages.figures` hide from us the CSS or XPath selectors that let us find child elements like `.pages`.  But sometimes, the default selector we have isn't what is used in a certain book.  In these cases, we can override the selector once in the recipe and still continue to use the book-oriented usage.  For example, a page summary is normally found using the CSS `section.summary`.  But some books use a `.section-summary` class.  For these books, we can override the selectors in their recipes:
+
+```ruby
+recipe = Kitchen::BookRecipe.new do |doc|
+  doc.selectors.override(
+    page_summary: ".section-summary"
+  )
+```
+
 ## Directions
 
 All of the above talks about the how to search through the XML file and perform basic operations on that file.  Our recipes will be combinations of all of the above: search for elements; cut, copy and paste them; count them; rework them; etc.
@@ -430,10 +464,10 @@ Want to make a one-file script to do some baking?  Use the "inline" form of bund
 require "bundler/inline"
 
 gemfile do
-  gem 'kitchen', git: 'https://github.com/openstax/kitchen.git', ref: 'some_sha_here'
+  gem 'openstax_kitchen', '2.0.0'
 end
 
-require "kitchen"
+require "openstax_kitchen"
 
 recipe = Kitchen::Recipe.new do |doc|
   # ... recipe steps here
@@ -452,19 +486,23 @@ Incidentally, the `bake` method returns timing information, if you `puts` its re
 
 ### Docker
 
-You can use Docker for your development environment.
+You can use Docker for your development environment.  To build the image:
 
 ```bash
-$> docker-compose up -d
+$> ./docker/build
 ```
 
-to build and run the Docker container, then:
+To drop into the running container:
 
 ```bash
 $> ./docker/bash
 ```
 
-To drop into the container at the command line.
+To run specs (or something else) from the host:
+
+```bash
+$> ./docker/run rspec
+```
 
 ### Non-Docker
 
@@ -583,6 +621,8 @@ Run `yard server --reload` to watch for changes in your local codebase everytime
 
 Navidate to `http://localhost:8808/` to view documentation in your browser.
 
+Use the `inch` gem to get feedback on where documentation is lacking `bundle exec inch` (add `--help` for more options).
+
 ### Specs
 
 Run `bundle exec rspec` to run the specs.  `rake rspec` probably does the same thing.
@@ -609,7 +649,25 @@ expect(book_1).to match_html_nodes("some string of HTML here")
 4. Click "Remote-Containers: Open Folder in Container"
 5. Select the cloned kitchen folder.
 
-This (assuming you have Docker installed) will launch a docker container for Kitchen, install Ruby and needed libraries, and then let you edit the code running in that container through VSCode.  Solargraph will work (code completion and inline documentation).
+This (assuming you have Docker installed) will launch a docker container for Kitchen, install Ruby and needed libraries, and then let you edit the code running in that container through VSCode.  Solargraph will work (code completion and inline documentation) as will Rubocop for linting.
+
+### Rubocop
+
+Rubocop is good for helping us keep our code style standardized, but it isn't the end-all be-all of things.  We can disable certain checks within a file, e.g.
+
+```ruby
+# rubocop:disable Style/NumericPredicate
+```
+
+or we can disable or change global settings in the `.rubocop.yml` file.
+
+Rubocop is setup to run within the VSCode dev container (see above).
+
+The [lefthook](https://github.com/Arkweid/lefthook) is included in the Docker build.  When you push your code to GitHub, lefthook runs Rubocop on all the files you have changed.  It won't let you push if you have Rubocop errors.  You'll have to fix the errors or make changes to the `.rubocop.yml` files to bypass the errors.  You can also run lefthook directly with
+
+```bash
+$ /code> lefthook run pre-push
+```
 
 #### Misc References
 
@@ -643,13 +701,9 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## TODO
 
 * Specs galore :-)
-  * `$` search path substitution (making sure not to mess up xpath)
 * Think up and handle a bunch more recipe errors, test they all raise some kind of `RecipeError`.
 * Encapsulate numbering schemes (e.g. chapter pages are "5.2", appendix pages are "D7") and maybe set on book document?  Right now we are doing inline things like `*('A'..'Z')][page.count_in(:book)-1]}#{table.count_in(:page)` which is ugly.
-* Add rubocop for linting.
 * Control I18n language in Oven.
-* Get doc normalization scripts into this repo from testkitchen (for comparing two large baked outputs).
-* Change from ElementBase <- Element to Element <- BasicElement
 * README: element_children, .only, selectors, config files
 * Use ERB for more readable string building?
 

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 "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 "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,15 @@
+#!/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 \
+           -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,24 +1,59 @@
+# 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,
-            enumerator_class: BookElementEnumerator,
-            short_type: :book)
+            enumerator_class: BookElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.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
 
+    # 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 == 'body'
+    end
   end
 end