epub_tools 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbc80ed0690251633b8f12d80fa256922cac6092c12d3a910cd998e61ce38ea0
-  data.tar.gz: b0da7dd401516d3a1074268c7495d02d1a3532ea3e6f4bd9b49b9e62772e280c
+  metadata.gz: 815d8970acc779f70f7d86395a3658a296536675539dfcf3e7f9a0e0f2d4153a
+  data.tar.gz: da9131f5868b8e8c438e9f41c526d62a2d9f70a320e8d20fa14ffcf4a487f22c
 SHA512:
-  metadata.gz: 66de9b943051874b87a1a32bf7fba1391eefad09e21a20f1e5a9265cdcb77d65bc453342787dc25944a265a81cf1119ecfe37a78713221d6d869aae4896982d9
-  data.tar.gz: db68ab8011facd49ef7314d1b6e7ce0c2b645a62a3a4ae213048af2500546622b55153cc4598747d234a972c05738927ec7f9b9efb047feb0c60c3022a6f21fa
+  metadata.gz: a7dc1015fc79f4c72edec8fb672622122a3540ef3b8923683777a178d397fff5af4e0b0765f237e748ca7a103b9e4c2c0c0c0902d180fcd9cb87e90c613c862f
+  data.tar.gz: fe60fa02c6a7db816b7aab2f5fe368de1a463fdaaa5aa1892146281362ea2cda49d904da541b67e34b2329225e01d9fcc7cd9a3a4c15503cb06cf3d6a10e26ec

data/.document

@@ -0,0 +1,2 @@
+lib
+bin

data/.github/workflows/ci.yml

@@ -2,20 +2,21 @@ name: CI
 
 on:
   push:
-    branches: ["main"]
+    branches: [ main ]
   pull_request:
-    branches: ["main"]
+    branches: [ main ]
 
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ['3.2', '3.3', '3.4']
     steps:
       - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.4.3'
-          bundler-cache: true
-      - name: Install dependencies
-        run: bundle install --jobs 4 --retry 3
-      - name: Run tests
-        run: bundle exec rake test
+          ruby-version: ${{ matrix.ruby }}
+      - run: gem install bundler
+      - run: bundle install --jobs 4 --retry 3
+      - run: bundle exec rake test

data/.gitignore

@@ -1,6 +1,8 @@
 .DS_Store
 /.bundle/
 /coverage/
+/doc/
+/.yardoc/
 vendor/bundle/
 *.gem
 

data/Gemfile

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-ruby '3.4.3'
+ruby '>= 3.2'
 
 source "https://rubygems.org"
 
@@ -12,3 +12,8 @@ group :test do
   gem "minitest", "~> 5.25"
   gem "simplecov", require: false
 end
+
+group :doc do
+  gem "yard", "~> 0.9.37"
+end
+

data/Gemfile.lock

@@ -28,6 +28,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
+    yard (0.9.37)
 
 PLATFORMS
   aarch64-linux-gnu
@@ -45,6 +46,7 @@ DEPENDENCIES
   rake (~> 13.2)
   rubyzip (~> 2.4)
   simplecov
+  yard (~> 0.9.37)
 
 RUBY VERSION
    ruby 3.4.3p32

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jaime Rodas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,6 +1,8 @@
  # EPUB Tools
 
- **TL;DR:** A Ruby gem and CLI for working with EPUB files: extract, split, initialize, add chapters, pack, and unpack EPUB books.
+[![Build Status](https://github.com/jaimerodas/epub_tools/actions/workflows/ci.yml/badge.svg)](https://github.com/jaimerodas/epub_tools/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**TL;DR:** A Ruby gem and CLI for working with EPUB files: extract, split, initialize, add chapters, pack, and unpack EPUB books.
 
 ## Installation
 Install the gem via RubyGems:
@@ -52,7 +54,7 @@ epub-tools pack -i epub_dir -o MyBook.epub
 
 # Unpack EPUB
 epub-tools unpack -i MyBook.epub -o unpacked_dir
-  
+
 # Full compile workflow: extract, split, initialize, add, and pack into one EPUB
 epub-tools compile -t "My Book" -a "Author Name" -s source_epubs -c cover.jpg -o MyBook.epub
 ```
@@ -88,7 +90,7 @@ EpubTools::EpubInitializer.new(
 ).run
 
 # Add chapters
-EpubTools::AddChaptersToEpub.new('chapters', 'epub_dir/OEBPS').run
+EpubTools::AddChapters.new('chapters', 'epub_dir/OEBPS').run
 
 # Pack EPUB
 EpubTools::PackEbook.new('epub_dir', 'MyBook.epub').run

data/bin/epub-tools

@@ -36,7 +36,7 @@ EpubTools::CLIHelper.parse(options, [:chapters_dir, :epub_oebps_dir]) do |opts,
   opts.on('-e DIR', '--epub-oebps-dir DIR', 'EPUB OEBPS directory (required)') { |v| o[:epub_oebps_dir] = v }
 end
 
-EpubTools::AddChaptersToEpub.new(options[:chapters_dir], options[:epub_oebps_dir]).run
+EpubTools::AddChapters.new(options[:chapters_dir], options[:epub_oebps_dir]).run
 
 when 'extract'
   options = { verbose: true }

data/epub_tools.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files`.split("\n")
   spec.require_paths = ['lib']
   spec.executables   = ['epub-tools']
-  spec.required_ruby_version = ">= 3.0"
+  spec.required_ruby_version = ">= 3.2"
   spec.metadata    = {
     "source_code_uri" => "https://github.com/jaimerodas/epub_tools/tree/main",
     "homepage_uri" => "https://github.com/jaimerodas/epub_tools"

data/lib/epub_tools/{add_chapters_to_epub.rb → add_chapters.rb}

@@ -3,7 +3,16 @@ require 'nokogiri'
 require 'fileutils'
 
 module EpubTools
-  class AddChaptersToEpub
+  # Moves new chapters into an unpacked EPUB
+  class AddChapters
+    # :args: chapters_dir, epub_dir, verbose:
+    # [chapters_dir] Directory from which to move the xhtml chapters. It assumes the
+    #                directory will contain one or more files named +chapter_XX.xhtml+,
+    #                where +XX+ is a number. Defaults to +./chapters+.
+    # [epub_dir] Unpacked EPUB directory to move the chapters to. It should be the same
+    #            directory that contains the +package.opf+ and +nav.xhtml+ files. Defaults
+    #            to +./epub/OEBPS+.
+    # [verbose:] Whether to log progress to +STDOUT+ or not. Defaults to +false+.
     def initialize(chapters_dir = './chapters', epub_dir = './epub/OEBPS', verbose = false)
       @chapters_dir = chapters_dir
       @epub_dir = epub_dir
@@ -12,6 +21,12 @@ module EpubTools
       @verbose = verbose
     end
 
+    # It works like this:
+    # - First, the *.xhtml files are moved from +chapters_dir+ over to +epub_dir+
+    # - Then, new entries will be added to the manifest and spine of the EPUB's +package.opf+ file.
+    #   It will sort the files by extracting the chapter number.
+    # - Finally, it will update the +nav.xhtml+ file with the new chapters. Note that if there's a
+    #   file named +chapter_0.xhtml+, it will be added to the +nav.xhtml+ as the Prologue.
     def run
       moved_files = move_chapters
       update_package_opf(moved_files)

data/lib/epub_tools/compile_book.rb

@@ -3,17 +3,28 @@ require 'fileutils'
 require_relative 'xhtml_extractor'
 require_relative 'split_chapters'
 require_relative 'epub_initializer'
-require_relative 'add_chapters_to_epub'
+require_relative 'add_chapters'
 require_relative 'pack_ebook'
 
 module EpubTools
   # Orchestrates extraction, splitting, validation, and packaging of book EPUBs
   class CompileBook
-    attr_reader :title, :author, :source_dir, :cover_image, :output_file, :build_dir, :verbose
-
-    # title: String, author: String, source_dir: path to input epubs
-    # cover_image: optional path to cover image, output_file: filename for final epub
-    # build_dir: optional working directory for intermediate files
+    # Book title
+    attr_reader :title
+    # Book author
+    attr_reader :author
+    # Path of the input epubs
+    attr_reader :source_dir
+    # Optional path to the cover image
+    attr_reader :cover_image
+    # Filename for the final epub
+    attr_reader :output_file
+    # Optional working directory for intermediate files
+    attr_reader :build_dir
+    # Whether to print progress to STDOUT
+    attr_reader :verbose
+
+    # Initializes the class
     def initialize(title:, author:, source_dir:, cover_image: nil, output_file: nil, build_dir: nil, verbose: false)
       @title       = title
       @author      = author
@@ -113,7 +124,7 @@ module EpubTools
 
     def add_chapters
       log "Adding chapters to EPUB..."
-      AddChaptersToEpub.new(chapters_dir, File.join(epub_dir, 'OEBPS'), verbose).run
+      AddChapters.new(chapters_dir, File.join(epub_dir, 'OEBPS'), verbose).run
     end
 
     def pack_epub

data/lib/epub_tools/epub_initializer.rb

@@ -4,9 +4,19 @@ require 'time'
 require 'securerandom'
 
 module EpubTools
+  # Sets up a basic empty EPUB directory structure with the basic files created:
+  # - +mimetype+
+  # - +container.xml+
+  # - +title.xhtml+ as a title page
+  # - +package.opf+
+  # - +nav.xhtml+ as a table of contents
+  # - +style.css+ a basic style inherited from the repo
+  # - cover image (optionally)
   class EpubInitializer
-    # title: book title; author: author name; destination: output EPUB directory
-    # cover_image: optional path to cover image file
+    # [title] Book title
+    # [author] Book Author
+    # [destination] Target directory
+    # [cover_image] Optional image path to use as a cover for the book
     def initialize(title, author, destination, cover_image = nil)
       @title = title
       @author = author
@@ -18,6 +28,7 @@ module EpubTools
       @cover_image_media_type = nil
     end
 
+    # Creates the empty ebook and returns the directory
     def run
       create_structure
       write_mimetype
@@ -27,6 +38,7 @@ module EpubTools
       write_package_opf
       write_nav
       write_style
+      @destination
     end
 
     private

data/lib/epub_tools/pack_ebook.rb

@@ -5,8 +5,8 @@ require 'pathname'
 module EpubTools
   # Packages an EPUB directory into a .epub file
   class PackEbook
-    # input_dir: path to the EPUB directory (containing mimetype, META-INF, OEBPS)
-    # output_file: path to resulting .epub file; if nil, defaults to <input_dir>.epub
+    # [input_dir] Path to the EPUB directory (containing mimetype, META-INF, OEBPS)
+    # [output_file] Path to resulting .epub file; if +nil+, defaults to <tt><input_dir>.epub</tt>
     def initialize(input_dir, output_file = nil, verbose: false)
       @input_dir = File.expand_path(input_dir)
       default_name = "#{File.basename(@input_dir)}.epub"
@@ -18,7 +18,7 @@ module EpubTools
       @verbose = verbose
     end
 
-    # Run the packaging process
+    # Runs the packaging process and returns the resulting file path
     def run
       validate_input!
       Dir.chdir(@input_dir) do
@@ -38,6 +38,7 @@ module EpubTools
         end
       end
       puts "EPUB created: #{@output_file}" if @verbose
+      @output_file
     end
 
     private

data/lib/epub_tools/split_chapters.rb

@@ -5,11 +5,19 @@ require_relative 'text_style_class_finder'
 require_relative 'xhtml_cleaner'
 
 module EpubTools
+  # Takes a Google Docs generated, already extracted from their EPUB, XHTML files with multiple
+  # chapters and it:
+  # - Extracts classes using {TextStyleClassFinder}[rdoc-ref:EpubTools::TextStyleClassFinder]
+  # - Looks for tags that say something like Chapter XX or Prologue and splits the text there
+  # - Creates new chapter_XX.xhtml files that are cleaned using
+  #   {XHTMLCleaner}[rdoc-ref:EpubTools::XHTMLCleaner]
+  # - Saves those files to +output_dir+
   class SplitChapters
-    # input_file: path to the source XHTML
-    # book_title: title to use in HTML <title> tags
-    # output_dir: where to write chapter files
-    # output_prefix: filename prefix (e.g. "chapter")
+    # [input_file] path to the source XHTML
+    # [book_title] title to use in HTML <title> tags
+    # [output_dir] where to write chapter files
+    # [output_prefix] filename prefix. Defaults to 'chapter' and you should never need to change it
+    # [verbose] whether to print progress to STDOUT.
     def initialize(input_file, book_title, output_dir = './chapters', output_prefix = 'chapter', verbose = false)
       @input_file    = input_file
       @book_title    = book_title
@@ -18,12 +26,13 @@ module EpubTools
       @verbose       = verbose
     end
 
+    # Runs the splitter
     def run
       # Prepare output dir
       Dir.mkdir(@output_dir) unless Dir.exist?(@output_dir)
 
       # Read the doc
-      raw_content = read_and_strip_problematic_hr
+      raw_content = read_and_strip_problematic_tags
       doc = Nokogiri::HTML(raw_content)
 
       # Find Style Classes
@@ -35,7 +44,7 @@ module EpubTools
 
     private
 
-    def read_and_strip_problematic_hr
+    def read_and_strip_problematic_tags
       File.read(@input_file).gsub(/<hr\b[^>]*\/?>/i, '').gsub(/<br\b[^>]*\/?>/i, '')
     end
 

data/lib/epub_tools/text_style_class_finder.rb

@@ -3,7 +3,13 @@ require 'nokogiri'
 require 'yaml'
 
 module EpubTools
+  # Finds css classes for bold and italic texts in Google Docs-generated EPUBs. Used by
+  # {XHTMLCleaner}[rdoc-ref:EpubTools::XHTMLCleaner] and
+  # {SplitChapters}[rdoc-ref:EpubTools::SplitChapters].
   class TextStyleClassFinder
+    # [file_path] XHTML file to be analyzed.
+    # [output_path] Defaults to +text_style_classes.yaml+. You should never need to change this.
+    # [verbose] Whether to print progress or not
     def initialize(file_path, output_path = 'text_style_classes.yaml', verbose: false)
       @file_path = file_path
       @output_path = output_path
@@ -11,6 +17,7 @@ module EpubTools
       raise ArgumentError, "File does not exist: #{@file_path}" unless File.exist?(@file_path)
     end
 
+    # Runs the finder
     def call
       doc = Nokogiri::HTML(File.read(@file_path))
       style_blocks = doc.xpath('//style').map(&:text).join("\n")

data/lib/epub_tools/unpack_ebook.rb

@@ -4,20 +4,17 @@ require 'fileutils'
 module EpubTools
   # Unpacks an EPUB (.epub file) into a directory
   class UnpackEbook
-    # epub_file: path to the .epub file
-    # output_dir: directory to extract into; defaults to basename of epub_file without .epub
+    # [epub_file] path to the .epub file
+    # [output_dir] Directory to extract into; defaults to basename of epub_file without .epub
+    # [verbose] Whether to log things to $stdout while the class runs or not
     def initialize(epub_file, output_dir = nil, verbose: false)
       @epub_file = File.expand_path(epub_file)
-      default_dir = [File.dirname(@epub_file), File.basename(@epub_file, '.epub')].join("/")
-      @output_dir = if output_dir.nil? || output_dir.empty?
-                      default_dir
-                    else
-                      output_dir
-                    end
+      @output_dir = (output_dir.nil? || output_dir.empty?) ? default_dir: output_dir
       @verbose = verbose
     end
 
-    # Extracts all entries from the EPUB into the output directory
+    # Extracts all entries from the EPUB into the output directory. Returns the output
+    # directory.
     def run
       validate!
       FileUtils.mkdir_p(@output_dir)
@@ -33,10 +30,15 @@ module EpubTools
         end
       end
       puts "Unpacked #{File.basename(@epub_file)} to #{@output_dir}" if @verbose
+      @output_dir
     end
 
     private
 
+    def default_dir
+      [File.dirname(@epub_file), File.basename(@epub_file, '.epub')].join("/")
+    end
+
     def validate!
       unless File.file?(@epub_file)
         raise ArgumentError, "EPUB file '#{@epub_file}' does not exist"

data/lib/epub_tools/version.rb

@@ -1,3 +1,4 @@
 module EpubTools
-  VERSION = '0.3.0'
+  # Ruby Gem version number
+  VERSION = '0.3.1'
 end

data/lib/epub_tools/xhtml_cleaner.rb

@@ -4,12 +4,28 @@ require 'nokogiri'
 require 'yaml'
 
 module EpubTools
+  # Cleans Google Docs XHTMLs
+
+  # Google Docs makes a mess out of EPUBs and creates html without proper tag names and just uses
+  # classes for _everything_. This class does the following to clean invalid xhtml:
+  #
+  # - Removes any <tt><br /></tt> or <tt><hr /></tt> tags.
+  # - Removes empty <tt><p></tt> tags.
+  # - Using the +class_config+, it removes <tt><span></tt> tags that are used for bold or italics and
+  #   replaces them with <tt><b></tt> or <tt><i></tt> tags.
+  # - Unwraps any <tt><span></tt> tags that have no classes assigned.
+  # - Outputs everything to a cleanly formatted +.xhtml+
   class XHTMLCleaner
+    # [filename] The path to the xhtml to clean
+    # [class_config] A YAML containing the bold and italic classes to check. It defaults to
+    #                +text_style_classes.yaml+ since that's the one that
+    #                {TextStyleClassFinder}[rdoc-ref:EpubTools::TextStyleClassFinder] uses.
     def initialize(filename, class_config = 'text_style_classes.yaml')
       @filename = filename
       @classes = YAML.load_file(class_config).transform_keys(&:to_sym)
     end
 
+    # Calls the service class
     def call
       raw_content = read_and_strip_problematic_hr
       doc = parse_xml(raw_content)

data/lib/epub_tools/xhtml_extractor.rb

@@ -2,8 +2,11 @@ require 'zip'
 require 'fileutils'
 
 module EpubTools
-  # Extracts .xhtml files from EPUB archives, excluding nav.xhtml
+  # Extracts text .xhtml files from EPUB archives, excluding nav.xhtml
   class XHTMLExtractor
+    # [source_dir] Directory that has source .epub files
+    # [target_dir] Directory where the extracted .xhtml files will be copied to
+    # [verbose] Whether to print progress to +STDOUT+ or not
     def initialize(source_dir:, target_dir:, verbose: false)
       @source_dir = File.expand_path(source_dir)
       @target_dir = File.expand_path(target_dir)
@@ -11,6 +14,7 @@ module EpubTools
       FileUtils.mkdir_p(@target_dir)
     end
 
+    # Runs the extraction process
     def extract_all
       epub_files.each do |epub_path|
         extract_xhtmls_from(epub_path)
@@ -43,4 +47,4 @@ module EpubTools
       warn "⚠️ Failed to process #{epub_path}: #{e.message}"
     end
   end
-end
+end

data/lib/epub_tools.rb

@@ -1,5 +1,5 @@
 require_relative 'epub_tools/version'
-require_relative 'epub_tools/add_chapters_to_epub'
+require_relative 'epub_tools/add_chapters'
 require_relative 'epub_tools/cli_helper'
 require_relative 'epub_tools/epub_initializer'
 require_relative 'epub_tools/split_chapters'
@@ -9,5 +9,6 @@ require_relative 'epub_tools/pack_ebook'
 require_relative 'epub_tools/unpack_ebook'
 require_relative 'epub_tools/compile_book'
 
+# Wrapper for all the other classes
 module EpubTools
 end

data/test/{add_chapters_to_epub_test.rb → add_chapters_test.rb}

@@ -1,8 +1,8 @@
 require_relative 'test_helper'
-require_relative '../lib/epub_tools/add_chapters_to_epub'
+require_relative '../lib/epub_tools/add_chapters'
 require 'nokogiri'
 
-class AddChaptersToEpubTest < Minitest::Test
+class AddChaptersTest < Minitest::Test
   def setup
     @tmp = Dir.mktmpdir
     # Directories for chapters and EPUB OEBPS
@@ -54,7 +54,7 @@ class AddChaptersToEpubTest < Minitest::Test
 
   def test_run_moves_files_and_updates_opf_and_nav
     # Run the add chapters task
-    EpubTools::AddChaptersToEpub.new(@chapters_dir, @epub_dir).run
+    EpubTools::AddChapters.new(@chapters_dir, @epub_dir).run
 
     # Original chapter files should be moved
     assert_empty Dir.glob(File.join(@chapters_dir, '*.xhtml'))

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epub_tools
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Jaime Rodas
@@ -86,18 +86,20 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".document"
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".nova/Configuration.json"
 - ".ruby-version"
 - Gemfile
 - Gemfile.lock
+- LICENSE
 - README.md
 - Rakefile
 - bin/epub-tools
 - epub_tools.gemspec
 - lib/epub_tools.rb
-- lib/epub_tools/add_chapters_to_epub.rb
+- lib/epub_tools/add_chapters.rb
 - lib/epub_tools/cli_helper.rb
 - lib/epub_tools/compile_book.rb
 - lib/epub_tools/epub_initializer.rb
@@ -109,7 +111,7 @@ files:
 - lib/epub_tools/xhtml_cleaner.rb
 - lib/epub_tools/xhtml_extractor.rb
 - style.css
-- test/add_chapters_to_epub_test.rb
+- test/add_chapters_test.rb
 - test/cli_version_test.rb
 - test/compile_book_test.rb
 - test/epub_initializer_test.rb
@@ -133,7 +135,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="