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):

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)

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)

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)

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)

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:

$ rake

Contributing

Fork the openstax/content-ruby repo on Github
Create a feature or bugfix branch (git checkout -b my-new-feature)
Write tests for the feature/bugfix
Implement the new feature/bugfix
Make sure both new and old tests pass (rake)
Commit your changes (git commit -am 'Added some feature')
Push the branch (git push origin my-new-feature)
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.

openstax / content-ruby