openstax_kitchen 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47c8699f2836cea06df2e5a97aa79c350662e8193c9c1abfafd50740de61cbf6
-  data.tar.gz: 2384b847a91f55624ca266274fb273f98cfcaeb81962c988b04efcb0d619f2a1
+  metadata.gz: f404296c40eba5dbfdeeb4c4de0d11492eb327e94d49c96689b262a03bc838de
+  data.tar.gz: b97faf532e7e098dba23ef1d1f3c42ca7c051d7fc6ad8351fa6b20209cb99ddd
 SHA512:
-  metadata.gz: 6a617ef7617b5ebb0ae959615125a82945f965fcb7cbc080eff8da974fb843bd81fc72226fc62d9439f9012d95af21c80e6d85d81a1a0594c7b7546d8fd6e6f8
-  data.tar.gz: cad462c3c8809912d290148a5c5f64fd8518bd8043ba66d315babeed504dc083761014abd038a9fea8eb88caaa9dcc930be4f9c0b4f048e3590a0645b8bf0da9
+  metadata.gz: 7f8e774352355cc44b01765b101e97db3128e19e7416a6d5138d0a83db4378e7910d196e42849237e2130c6f7463db6f13679d53ac666b6a0abf6f867ecf6a36
+  data.tar.gz: 84fece5f5d36f16324022d3ca34b6827f6549bed21551caedbb2845ff41d5b7b1f4b47c8e07a6fac6b14ed2e5f092435b63618a3b9e0f925a40cda21b04babfb

data/.devcontainer/devcontainer.json

@@ -1,19 +1,39 @@
 {
- "name": "Kitchen Dev",
- "dockerComposeFile": ["../docker-compose.yml"],
- "service": "app",
- "workspaceFolder": "/code",
- "shutdownAction": "stopCompose",
- "extensions": [
-   "castwide.solargraph",
- ],
- "settings": {
-   "[ruby]": {
-     "editor.insertSpaces": true,
-     "editor.tabSize": 2
-   },
-   "solargraph.commandPath": "/usr/local/bundle/bin/solargraph",
-   "solargraph.bundlerPath": "/usr/local/bin/bundle",
- },
- "postCreateCommand": "bundle install"
+  "name": "Kitchen Dev",
+  "build": {
+    "dockerfile": "../docker/Dockerfile",
+    "context": "..",
+    "args": {
+      "bundler_version": "2.2.4"
+    }
+  },
+  "workspaceMount": "source=${localWorkspaceFolder},target=/code,type=bind,consistency=default",
+  "workspaceFolder": "/code",
+  "extensions": [
+    "castwide.solargraph",
+    "rebornix.Ruby",
+    "MS-vsliveshare.vsliveshare-pack"
+  ],
+  "settings": {
+    "files.trimTrailingWhitespace": true,
+    "files.insertFinalNewline": true,
+    "terminal.integrated.shell.linux": "/bin/bash",
+    "[ruby]": {
+      "editor.insertSpaces": true,
+      "editor.tabSize": 2,
+    },
+    "ruby.lint": {
+      "rubocop": {
+        "useBundler": true // enable rubocop via bundler
+      },
+    },
+    "ruby.format": "rubocop", // use rubocop for formatting
+    "ruby.useLanguageServer": true,
+    "solargraph.commandPath": "/usr/local/bundle/bin/solargraph",
+    "solargraph.bundlerPath": "/usr/local/bin/bundle",
+    "ruby.rubocop.executePath": "/usr/local/bundle/bin/",
+    "ruby.rubocop.onSave": true,
+    "ruby.rubocop.configFilePath": "/code/.rubocop.yml",
+    "terminal.integrated.scrollback": 100000
+  }
 }

data/.github/config.yml

@@ -0,0 +1,14 @@
+# See https://github.com/openstax/staxly#plugins for more options for this file
+changelog:
+  # See https://github.com/mikz/probot-changelog for details
+
+  # The filename of the CHANGELOG that needs to be updated in every PullRequest
+  filename: CHANGELOG.md
+
+  # (optional) when files matching these patterns are changed then disallow merging
+  # until the CHANGELOG is updated.
+  # If this pattern is not included then **all** Pull Requests require an edit to 
+  # the CHANGELOG file
+  
+  # include:
+  #   - /^src\//

data/.github/workflows/tests.yml

@@ -5,32 +5,22 @@ on:
   push:
     branches:
       - main
-  schedule:
-    - cron: '0 0 * * 0' # weekly
 
 jobs:
-  tests:
+  rspec:
     timeout-minutes: 10
     runs-on: ubuntu-18.04
 
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-ruby@v1
-        with:
-          ruby-version: 2.6
       - uses: actions/cache@v2
         with:
           path: vendor/bundle
           key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
           restore-keys: |
             ${{ runner.os }}-gems-
-      - name: Test
-        env:
-          ENABLE_CODECOV: 1
+      - name: Build docker image and run specs within it
+        # See https://docs.codecov.io/docs/testing-with-docker
         run: |
-          gem install bundler --force --no-document --version 2.1.4
-          bundle config deployment true
-          bundle config path vendor/bundle
-          bundle config jobs 2
-          bundle install
-          bundle exec rake
+          ./docker/build --ci
+          CI_ENV=`bash <(curl -s https://codecov.io/env)` ./docker/ci

data/.gitignore

@@ -10,7 +10,7 @@
 
 # rspec failure tracking
 .rspec_status
-.irb_history
+.irb-history
 .byebug_history
 bin/scratch
 tutorial/outputs/*.html

data/.inch.yml

@@ -0,0 +1,6 @@
+files:
+  # define files excluded from the analysis (defaults to [])
+  excluded:
+    - lib/kitchen/directions/**/*.rb # may want to add this in later in a limited way
+    - lib/kitchen/debug/**/*.rb
+    - lib/openstax_kitchen.rb

data/.rubocop.yml

@@ -0,0 +1,65 @@
+AllCops:
+  TargetRubyVersion: 2.4
+
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 100
+  IgnoredPatterns: ['(\A|\s)#']
+
+Metrics/AbcSize:
+  Max: 50
+
+Naming/PredicateName:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 300
+  CountAsOne: ['heredoc']
+
+Metrics/MethodLength:
+  Max: 50
+  CountAsOne: ['heredoc']
+
+Metrics/BlockLength:
+  CountAsOne: ['heredoc']
+  Max: 30
+  Exclude:
+    - 'openstax_kitchen.gemspec'
+
+Metrics/ModuleLength:
+  CountAsOne: ['heredoc']
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/StringLiterals:
+  ConsistentQuotesInMultiline: true
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: no_space
+
+Style/AccessorGrouping:
+  EnforcedStyle: separated
+
+Style/SingleLineMethods:
+  Enabled: false # don't abuse it, but sometimes it is right
+
+Style/RegexpLiteral:
+  AllowInnerSlashes: true
+
+Style/SymbolProc:
+  IgnoredMethods:
+    - respond_to
+    - define_method
+    - XML # For Nokogiri::XML
+
+Layout/ClosingParenthesisIndentation:
+  Enabled: false # when true hanging parens look weird
+
+Layout/MultilineMethodCallBraceLayout:
+  Enabled: false

data/CHANGELOG.md

@@ -6,8 +6,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.0] - 2021-03-17
+
+* Added a subfigure? method to `FigureElements`(minor)
+* Added support for titles in `BakeFigure` (minor)
+* Created `BakeUnitTitle` class
+* Created `UnitElement` and `UnitElementEnumerator` classes (minor)
+* Added support for Units in `BakeToc` direction (minor)
+* Added `Unit` to `en.yml` (patch)
+* Remove chapter summary titles only if they exist (minor)
+* Created `BakeSuggestedReading` direction for EOC
+* Added ability to filter searches based on `only` and `except` conditions, which can be names of element methods or blocks of code (minor)
+* Changed from tracking and using `css_or_xpath` strings and arrays to `search_query` objects that
+  wrap `css_or_xpath` variables along with `only` and `except` conditions. (major?)
+
 ## [2.0.0] - 2020-12-18
 
+* Refactored bake_exercises to better support parallel work on multiple versions.
+(minor change) Does not affect existing recipes.
 * Changed the main gem source file to have the same name as the gem (`openstax_kitchen`) so that you don't have to `require` a different name than you use in your `gem` call.
 
 ## [1.0.0] - 2020-12-15

data/Gemfile

@@ -1,9 +1,11 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in kitchen.gemspec
 gemspec
 
-gem "rake", "~> 12.0"
-gem "rspec", "~> 3.0"
+gem 'rake', '~> 12.0'
+gem 'rspec', '~> 3.0'
 
 gem 'codecov', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openstax_kitchen (2.0.0)
+    openstax_kitchen (3.0.0)
       activesupport
       i18n
       nokogiri
@@ -16,23 +16,43 @@ GEM
       minitest (~> 5.1)
       tzinfo (~> 1.1)
       zeitwerk (~> 2.2, >= 2.2.2)
+    ast (2.4.1)
     byebug (11.1.2)
     codecov (0.2.13)
       simplecov (~> 0.18.0)
+    coderay (1.1.3)
     concurrent-ruby (1.1.7)
     diff-lcs (1.3)
     docile (1.3.3)
     i18n (1.8.5)
       concurrent-ruby (~> 1.0)
-    mini_portile2 (2.4.0)
+    inch (0.8.0)
+      pry
+      sparkr (>= 0.2.0)
+      term-ansicolor
+      yard (~> 0.9.12)
+    method_source (1.0.0)
+    mini_portile2 (2.5.0)
     minitest (5.14.2)
-    nokogiri (1.10.9)
-      mini_portile2 (~> 2.4.0)
+    nokogiri (1.11.1)
+      mini_portile2 (~> 2.5.0)
+      racc (~> 1.4)
+    nokogiri (1.11.1-x86_64-linux)
+      racc (~> 1.4)
     nokogiri-diff (0.2.0)
       nokogiri (~> 1.5)
       tdiff (~> 0.3, >= 0.3.2)
+    parallel (1.20.1)
+    parser (2.7.2.0)
+      ast (~> 2.4.1)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.5.2)
     rainbow (3.0.0)
     rake (12.3.3)
+    regexp_parser (2.0.1)
+    rexml (3.2.4)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
@@ -46,29 +66,58 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
     rspec-support (3.9.2)
+    rubocop (1.6.1)
+      parallel (~> 1.10)
+      parser (>= 2.7.1.5)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.2.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.3.0)
+      parser (>= 2.7.1.5)
+    rubocop-rake (0.5.1)
+      rubocop
+    rubocop-rspec (2.1.0)
+      rubocop (~> 1.0)
+      rubocop-ast (>= 1.1.0)
+    ruby-progressbar (1.10.1)
     simplecov (0.18.5)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
     simplecov-html (0.12.3)
+    sparkr (0.4.1)
+    sync (0.5.0)
     tdiff (0.3.4)
+    term-ansicolor (1.7.1)
+      tins (~> 1.0)
     thread_safe (0.3.6)
+    tins (1.26.0)
+      sync
     tzinfo (1.2.7)
       thread_safe (~> 0.1)
+    unicode-display_width (1.7.0)
     yard (0.9.24)
     zeitwerk (2.4.0)
 
 PLATFORMS
   ruby
+  x86_64-linux
 
 DEPENDENCIES
   byebug
   codecov
+  inch
   nokogiri-diff
   openstax_kitchen!
   rainbow
   rake (~> 12.0)
   rspec (~> 3.0)
+  rubocop
+  rubocop-rake
+  rubocop-rspec
   yard
 
 BUNDLED WITH
-   2.1.4
+   2.2.4

data/README.md

@@ -3,7 +3,9 @@
 [![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
 
@@ -19,7 +21,7 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install kitchen
+    $ gem install openstax_kitchen
 
 ## Two Ways to Use Kitchen
 
@@ -271,6 +273,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.
@@ -452,19 +479,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 +614,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 +642,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 +694,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?