build

#!/usr/bin/env ruby

# https://bundler.io/guides/bundler_in_a_single_file_ruby_script.html
require 'bundler/inline'
puts 'Gems install and load...'
gemfile do
  source 'https://rubygems.org'
  gem 'RedCloth', '~> 4.3.2'
  gem 'ruby-handlebars', '~> 0.4.1'
  gem 'kramdown', '~> 2.4.0'
end
puts 'Gems installed and loaded.'

SOURCE_PATH = File.expand_path('../../textile', __FILE__)
TEXTILE_EXTENSION = '.textile'
MARKDOWN_EXTENSION = '.md'
ROOT_SOURCE_NAME = 'index'
TEMPLATE_PATH = File.expand_path('../../templates/docs-textile.html.hbs', __FILE__)
OUTPUT_PATH = File.expand_path('../../output', __FILE__)
COPYRIGHT_PATH = File.expand_path('../../COPYRIGHT', __FILE__)
META_PATH = File.expand_path('../../meta.yaml', __FILE__)

BUILD_CONTEXT_SHA = ENV['ABLY_BUILD_CONTEXT_SHA']
BUILD_CONTEXT_URL = ENV['ABLY_BUILD_CONTEXT_URL']
BUILD_CONTEXT_TITLE = ENV['ABLY_BUILD_CONTEXT_TITLE']
COPYRIGHT = File.read(COPYRIGHT_PATH)

Dir.mkdir OUTPUT_PATH

# Ably extension atop textile / RedCloth. See:
# - https://github.com/ably/docs/blob/4edc37a8aae13995d63b7962b27b091f354f4597/lib/ably_pre_textile_filter.rb#L374
# - https://github.com/jgarber/redcloth/blob/dd7ee6caaa6c899f4d5389c1b2fe4a17f1e5f326/spec/extension_spec.rb#L4
module RedClothExtension
  # A RedCloth rule which returns a copy of the given textile content with
  # bulleted spec points converted into anchor links.
  #
  # For example, a spec point like:
  #
  #     * @(RTL18)@
  #
  # is replaced with:
  #
  #     * <a id='RTL18' name='RTL18' href='#RTL18'>@(RTL18)@</a>
  #
  def add_spec_anchor_links(textile_content)
    textile_content.gsub!(/\* @\((\w+)\)@/) do |m|
      spec_id = $1
      "* <a id='#{spec_id}' name='#{spec_id}' href='##{spec_id}'>@(#{spec_id})@</a>"
    end
  end
end
RedCloth.send(:include, RedClothExtension)
REDCLOTH_RULES = [:add_spec_anchor_links]

def remove_frontmatter(file_contents)
  had_frontmatter = false
  in_frontmatter = false
  body_contents = ''
  file_contents.lines.each do |line|
    if had_frontmatter
      body_contents << line
    else
      # either we are yet to encounter frontmatter, or we're within it
      if line.strip == '---'
        if in_frontmatter
          had_frontmatter = true
          in_frontmatter = false
        else
          in_frontmatter = true
        end
      end
    end
  end
  body_contents
end

versions = YAML.load_file(META_PATH)['versions']

handlebars = Handlebars::Handlebars.new
template = handlebars.compile(File.read(TEMPLATE_PATH))

textile_file_names = Dir.children(SOURCE_PATH).select {
  |file_name| file_name.end_with? "#{TEXTILE_EXTENSION}"
}.sort

markdown_file_names = Dir.children(SOURCE_PATH).select {
  |file_name| file_name.end_with? "#{MARKDOWN_EXTENSION}"
}.sort

plain_file_names = (textile_file_names + markdown_file_names).collect {
  |file_name| file_name.delete_suffix(TEXTILE_EXTENSION).delete_suffix(MARKDOWN_EXTENSION)
} - [ROOT_SOURCE_NAME]

textile_file_names.each do |file_name|
  print "#{file_name} ... "

  # We could possibly have used the Handlebars gem we're using elsewhere for this, however it was barfing on features.textile for no clear reason.
  # Regular expression find and replace (gsub) works for our simple needs here, so we're using that for simplicity.
  textile = remove_frontmatter(File.read(File.join(SOURCE_PATH, file_name)))
    .gsub(/\{\{\s*SPECIFICATION_VERSION\s*\}\}/, versions['specification'].to_s)
    .gsub(/\{\{\s*PROTOCOL_VERSION\s*\}\}/, versions['protocol'].to_s)

  bodyHtml = RedCloth.new(textile, [:no_span_caps]).to_html(*REDCLOTH_RULES)
  plain_file_name = file_name.delete_suffix(TEXTILE_EXTENSION)
  is_root = (plain_file_name == ROOT_SOURCE_NAME)
  html = template.call({
    bodyContent: bodyHtml,
    title: plain_file_name.capitalize(),
    file_names: plain_file_names - [plain_file_name],
    root_path: is_root ? '' : '../',
    copyright: COPYRIGHT,
    build_context_title: BUILD_CONTEXT_TITLE,
    build_context_url: BUILD_CONTEXT_URL,
    build_context_sha: BUILD_CONTEXT_SHA,
  })
  folder_path = is_root ? OUTPUT_PATH : File.join(OUTPUT_PATH, plain_file_name)
  if !is_root
    Dir.mkdir folder_path
  end
  File.write(File.join(folder_path, "index.html"), html)
  puts "✓"
end

markdown_file_names.each do |file_name|
  print "#{file_name} ... "

  markdown_content = remove_frontmatter(File.read(File.join(SOURCE_PATH, file_name)))
    .gsub(/\{\{\s*SPECIFICATION_VERSION\s*\}\}/, versions['specification'].to_s)
    .gsub(/\{\{\s*PROTOCOL_VERSION\s*\}\}/, versions['protocol'].to_s)

  bodyHtml = Kramdown::Document.new(markdown_content).to_html
  plain_file_name = file_name.delete_suffix(MARKDOWN_EXTENSION)
  is_root = (plain_file_name == ROOT_SOURCE_NAME)
  html = template.call({
    bodyContent: bodyHtml,
    title: plain_file_name.capitalize(),
    file_names: plain_file_names - [plain_file_name],
    root_path: is_root ? '' : '../',
    copyright: COPYRIGHT,
    build_context_title: BUILD_CONTEXT_TITLE,
    build_context_url: BUILD_CONTEXT_URL,
    build_context_sha: BUILD_CONTEXT_SHA,
  })
  folder_path = is_root ? OUTPUT_PATH : File.join(OUTPUT_PATH, plain_file_name)
  if !is_root
    Dir.mkdir folder_path
  end
  File.write(File.join(folder_path, "index.html"), html)
  puts "✓"
end