openstax_content 0.0.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 438e6037471accd85a41ff64543ef625e22d670121b1491eaa6c4d3827f4228b
-  data.tar.gz: 91b8fb852646355aad1c892e9a1fbfd0d54f3fd03ac5c4a286239ae10f51a710
+  metadata.gz: 760f80ecbe0193cdb9597862fd3d62e2bd687affa9c392ca07cd41440f5e7a62
+  data.tar.gz: f357ee9efc8c537f6c84c8e02fc15e0919691be79be677e413ba7542220a1ab0
 SHA512:
-  metadata.gz: 5c73997fedc8f642bbcda603fac97e1c071710464117f2de9ad4d2ef7cb648df4edcd0a71da2895442f196ad214dbdd3c7bc8a43e4aba2549bf2d97832a59a8a
-  data.tar.gz: e73e524ac9ea295f635b9388aae5e73ec06a7e514ee74bf555f46df4d9a45af3d38baa1be12fdcef7c5c9c7ad77d5d036e09a289bb62c08ada89c5575a12419b
+  metadata.gz: 78bf8346586fea75e4cc1d5eed2f5e083a6feb75974f71838b83c90383f9df1f6742a47203a60d9e3e293b855b5bf30bbe7eb78e5536f1f6b4847757fc24b3a0
+  data.tar.gz: 162cf2c108e2c94e1c11dea32baf337c82ec0965783aa6358209b58888cc389ecc7953e637c802511ce167603f1b9081fb346e3e32b787304f9a4c6740fbe75b

data/README.md

@@ -1,2 +1,100 @@
+[![Tests](https://github.com/openstax/content-ruby/workflows/Tests/badge.svg)](https://github.com/openstax/content-ruby/actions/workflows/tests.yml)
+
 # content-ruby
 Ruby bindings to read and parse the OpenStax ABL and the content archive
+
+## Installation
+Add this gem to your Gemfile and then add the following configuration to your boot
+(for example, in a Rails initializer):
+
+```rb
+OpenStax::Content.configure do |config|
+  config.abl_url = ENV['OPENSTAX_CONTENT_ABL_URL']
+  config.archive_path = ENV['OPENSTAX_CONTENT_ARCHIVE_PATH']
+  config.bucket_name = ENV['OPENSTAX_CONTENT_BUCKET_NAME']
+  config.domain = ENV['OPENSTAX_CONTENT_DOMAIN']
+  config.exercises_search_api_url = ENV['OPENSTAX_CONTENT_EXERCISES_SEARCH_API_URL']
+  config.logger = defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+  config.s3_region = ENV['OPENSTAX_CONTENT_S3_REGION']
+  config.s3_access_key_id = ENV['OPENSTAX_CONTENT_S3_ACCESS_KEY_ID']
+  config.s3_secret_access_key = ENV['OPENSTAX_CONTENT_S3_SECRET_ACCESS_KEY']
+end
+```
+
+It's probably a good idea to read these values from environment variables
+s3_access_key_id and s3_secret_access_key are optional (you can use AWS instance roles instead)
+
+## Usage
+
+### Approved Book List (to get approved books and approved versions)
+```rb
+abl = OpenStax::Content::Abl.new
+approved_books = abl.approved_books
+approved_versions = abl.approved_versions
+```
+
+### S3 Bucket Listing (to get latest archive and book versions)
+```rb
+s3 = OpenStax::Content::S3.new
+if s3.bucket_configured?
+  latest_archive_version = s3.ls.last
+  latest_book_ids = s3.ls latest_archive_version
+  chosen_book = latest_book_ids.sample
+  book_uuid, book_version = chosen_book.split('@', 2)
+  book = OpenStax::Content::Book.new(
+    archive_version: latest_archive_version, uuid: book_uuid, version: book_version
+  )
+end
+```
+
+### Archive (to create archive links, load content and get book and page slugs)
+```rb
+archive = OpenStax::Content::Archive.new latest_archive_version
+
+book_id = "#{book_uuid}@#{book_version}"
+page_id = "#{book_id}:#{page_uuid}"
+
+book_url = archive.url_for book_id
+page_url = archive.url_for page_id
+
+book_json = archive.fetch book_id
+page_json = archive.fetch page_id
+
+book_hash = archive.json book_id
+page_hash = archive.json page_id
+
+book_slug = archive.slug book_id # or book_uuid
+page_slug = archive.slug page_id # or "#{book_uuid}:#{page_uuid}"
+```
+
+### Fragment Splitter (to split pages and create interactive readings)
+```rb
+fragment_splitter = OpenStax::Content::FragmentSplitter.new(
+  book.reading_processing_instructions, reference_view_url
+)
+fragment_splitter.split_into_fragments page.root
+```
+
+## Testing
+
+To run all existing tests for this gem, simply execute the following from the main folder:
+
+```sh
+$ rake
+```
+
+## Contributing
+
+1. Fork the openstax/content-ruby repo on Github
+2. Create a feature or bugfix branch (`git checkout -b my-new-feature`)
+3. Write tests for the feature/bugfix
+4. Implement the new feature/bugfix
+5. Make sure both new and old tests pass (`rake`)
+6. Commit your changes (`git commit -am 'Added some feature'`)
+7. Push the branch (`git push origin my-new-feature`)
+8. Create a new Pull Request to openstax/content-ruby on Github
+
+## License
+
+This gem is distributed under the terms of the AGPLv3 license.
+See the LICENSE file for details.

data/lib/openstax/content/archive.rb

@@ -48,6 +48,10 @@ class OpenStax::Content::Archive
     if uri.path.start_with?('../')
       uri.path = uri.path.sub('..', '')
       "#{base_url}#{uri.to_s}"
+    elsif uri.path.start_with?(OpenStax::Content.archive_path) ||
+          uri.path.start_with?("/#{OpenStax::Content.archive_path}")
+      uri.path.start_with?('/') ? "https://#{OpenStax::Content.domain}#{uri.to_s}" :
+                                  "https://#{OpenStax::Content.domain}/#{uri.to_s}"
     else
       uri.path = "#{uri.path.chomp('.json').chomp('.xhtml')}.json"
 
@@ -101,4 +105,29 @@ class OpenStax::Content::Archive
       slug
     end
   end
+
+  def webview_uri_for(page)
+    uri = if page.is_a?(Addressable::URI)
+      page
+    else
+      begin
+        Addressable::URI.parse page
+      rescue Addressable::URI::InvalidURIError
+        begin
+          Addressable::URI.parse "/#{page}"
+        rescue Addressable::URI::InvalidURIError
+          OpenStax::Content.logger.warn { "Invalid page url: \"#{page}\"" }
+
+          return page
+        end
+      end
+    end
+    object = uri.path.split('/').last
+    book_id, page_id = object.split(':', 2)
+    page_uuid = page_id.split('@', 2).first
+    book_slug = slug book_id
+    page_slug = slug object
+    uri.path = "books/#{book_slug}/pages/#{page_slug}"
+    Addressable::URI.join "https://#{OpenStax::Content.domain}", uri
+  end
 end

data/lib/openstax/content/fragment/html.rb

@@ -17,12 +17,21 @@ class OpenStax::Content::Fragment::Html < OpenStax::Content::Fragment
     super.except('node')
   end
 
-  def html?
-    !to_html.empty?
+  def blank?
+    return @blank unless @blank.nil?
+
+    @blank = if to_html.nil? || to_html.strip.empty?
+      true
+    else
+      node_without_title = node.dup
+      node_without_title.css('[data-type="document-title"]').remove
+      text = node_without_title.text
+      text.nil? || text.strip.empty?
+    end
   end
 
-  def blank?
-    !html?
+  def html?
+    !blank?
   end
 
   def node

data/lib/openstax/content/fragment_splitter.rb

@@ -40,9 +40,11 @@ class OpenStax::Content::FragmentSplitter
     # Flatten, remove empty nodes and transform remaining nodes into reading fragments
     result.map do |obj|
       next obj unless obj.is_a?(Nokogiri::XML::Node)
-      next if obj.content.nil? || obj.content.strip.empty?
 
-      OpenStax::Content::Fragment::Reading.new node: obj, reference_view_url: reference_view_url
+      fragment = OpenStax::Content::Fragment::Reading.new(
+        node: obj, reference_view_url: reference_view_url
+      )
+      fragment unless fragment.blank?
     end.compact.tap do |result|
       @media_nodes.each do |node|
         # Media processing instructions

data/lib/openstax/content/s3.rb

@@ -2,7 +2,7 @@ require 'aws-sdk-s3'
 
 class OpenStax::Content::S3
   def initialize
-    @ls = {}
+    @ls = Hash.new { |hash, key| hash[key] = Hash.new { |hash, key| hash[key] = {} } }
   end
 
   def bucket_name
@@ -21,24 +21,65 @@ class OpenStax::Content::S3
     )
   end
 
-  def ls(archive_version = nil)
-    return @ls[archive_version] unless @ls[archive_version].nil?
-    return unless bucket_configured?
-
+  # Returns the archive path for the given archive_version, book_id, page_uuid and extension
+  # If not all arguments are given, returns the prefix instead
+  def path_for(archive_version = nil, book_id = nil, page_uuid = nil, extension = nil)
     archive_path = OpenStax::Content.archive_path.chomp('/')
 
     if archive_version.nil?
-      prefix = "#{archive_path}/"
-      delimiter = '/'
+      "#{archive_path}/"
+    elsif book_id.nil?
+      "#{archive_path}/#{archive_version}/contents/"
+    elsif page_uuid.nil?
+      "#{archive_path}/#{archive_version}/contents/#{book_id}:"
+    elsif extension.nil?
+      "#{archive_path}/#{archive_version}/contents/#{book_id}:#{page_uuid}."
+    else
+      "#{archive_path}/#{archive_version}/contents/#{book_id}:#{page_uuid}.#{extension}"
+    end
+  end
+
+  # Without an archive version, returns a list of archive versions
+  # With an archive version, returns a list of book ids (uuid@version)
+  # With an archive version and a book, returns a list of page uuids
+  # With an archive version, book id and page uuid, returns the available extensions, if any
+  def ls(archive_version = nil, book_id = nil, page_uuid = nil)
+    return @ls[archive_version][book_id][page_uuid] \
+      unless @ls[archive_version][book_id][page_uuid].nil?
+    return unless bucket_configured?
+
+    prefix = path_for archive_version, book_id, page_uuid
+
+    delimiter = if archive_version.nil?
+      '/'
+    elsif book_id.nil?
+      ':'
+    elsif page_uuid.nil?
+      '.'
+    else
+      nil
+    end
+
+    responses = client.list_objects_v2 bucket: bucket_name, prefix: prefix, delimiter: delimiter
+
+    @ls[archive_version][book_id][page_uuid] = if page_uuid.nil?
+      responses.flat_map(&:common_prefixes).map do |common_prefix|
+        common_prefix.prefix.sub(prefix, '').chomp(delimiter)
+      end
     else
-      prefix = "#{archive_path}/#{archive_version}/contents/"
-      delimiter = ':'
+      responses.flat_map(&:contents).map { |content| content.key.sub(prefix, '') }
     end
+  end
 
-    @ls[archive_version] = client.list_objects_v2(
-      bucket: bucket_name, prefix: prefix, delimiter: delimiter
-    ).flat_map(&:common_prefixes).map do |common_prefix|
-      common_prefix.prefix.sub(prefix, '').chomp(delimiter)
+  # Checks all books for the given page uuid and returns the path to the first one found
+  def find_page(page_uuid, archive_version: nil, extension: 'json')
+    archive_version ||= ls.last
+
+    ls(archive_version).each do |book_id|
+      return path_for(archive_version, book_id, page_uuid, extension) \
+        if ls(archive_version, book_id, page_uuid).include?(extension)
     end
+
+    nil
   end
 end

data/lib/openstax/content/version.rb

@@ -1,5 +1,5 @@
 module OpenStax
   module Content
-    VERSION = '0.0.1'
+    VERSION = '0.2.1'
   end
 end

data/lib/{openstax/content.rb → openstax_content.rb}

@@ -11,4 +11,4 @@ module OpenStax
   end
 end
 
-Dir["#{__dir__}/content/**/*.rb"].each { |file| require file }
+Dir["#{__dir__}/openstax/content/**/*.rb"].each { |file| require file }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openstax_content
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Dante Soares
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-10 00:00:00.000000000 Z
+date: 2021-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-s3
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Ruby bindings to read and parse the OpenStax ABL and the content archive
 email:
 - dante.m.soares@rice.edu
@@ -117,7 +145,6 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- lib/openstax/content.rb
 - lib/openstax/content/abl.rb
 - lib/openstax/content/archive.rb
 - lib/openstax/content/book.rb
@@ -136,6 +163,7 @@ files:
 - lib/openstax/content/s3.rb
 - lib/openstax/content/title.rb
 - lib/openstax/content/version.rb
+- lib/openstax_content.rb
 homepage: https://github.com/openstax/content-ruby
 licenses:
 - AGPL-3.0