howdoc 0.1.0

data/lib/howdoc/narrator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module Howdoc
+  # Turns an action and its payload into a sentence. The engine never contains a
+  # sentence itself -- every one of them is an I18n key, so the vocabulary is
+  # translatable and an application can reword any instruction without touching
+  # the code that records it.
+  module Narrator
+    SCOPE = 'howdoc.actions'
+
+    class << self
+      # Keys that were asked for but not translated, reported once at the end of
+      # a run rather than silently producing a guide with holes in it.
+      def missing_keys
+        @missing_keys ||= []
+      end
+
+      def reset_missing_keys
+        @missing_keys = []
+      end
+
+      def call(action, locale:, **payload)
+        key = "#{SCOPE}.#{action}"
+        text = I18n.t(key, locale:, default: nil, **escape(payload))
+
+        if text.nil?
+          missing_keys << key unless missing_keys.include?(key)
+          return nil
+        end
+
+        text
+      end
+
+      # The label a reader would recognise for a form field.
+      #
+      # A translation under howdoc.fields wins, which is how a field whose
+      # generated name reads badly gets a proper name without any code knowing
+      # about it. Otherwise the configured convention applies.
+      def field_label(locator, locale:)
+        return '' if locator.nil?
+
+        translated = I18n.t("howdoc.fields.#{locator}", locale:, default: nil)
+        return translated if translated
+
+        Howdoc.config.field_label.call(locator)
+      end
+
+      # Rails names fields after the model that owns them, which is noise to
+      # anyone who does not know the schema, so the leading segment is dropped.
+      def humanize_locator(locator)
+        string = locator.to_s
+
+        if string.include?('[')
+          string.split('[').last.tr(']', '').tr('_', ' ').strip
+        elsif string.include?('_')
+          string.split('_').drop(1).join(' ')
+        else
+          string
+        end
+      end
+
+      private
+
+      # Translations carry the markup, values do not. Escaping here means a
+      # label containing an angle bracket cannot break the page it lands on.
+      def escape(payload)
+        payload.transform_values do |value|
+          value.is_a?(String) || value.is_a?(Symbol) ? ERB::Util.html_escape(value.to_s) : value
+        end
+      end
+    end
+  end
+end

data/lib/howdoc/recorder.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # The public recording API. Anything that wants to appear in a guide goes
+  # through here -- the Capybara wrappers the gem ships with, and equally an
+  # application's own helpers, which the engine cannot and should not know
+  # about. Every method is a no-op when documentation is switched off, so
+  # call sites need no guards of their own.
+  module Recorder
+    # Option keys the recorder consumes. They are removed from a Capybara
+    # option hash before it reaches Capybara, which would reject them.
+    OPTION_KEYS = %i[nodoc no_screenshot full_page screenshot].freeze
+
+    module_function
+
+    def current
+      Thread.current[:howdoc_document]
+    end
+
+    def current=(document)
+      Thread.current[:howdoc_document] = document
+    end
+
+    def recording?
+      Howdoc.config.enabled? && !current.nil?
+    end
+
+    # Removes the gem's own options from a Capybara option hash, mutating it,
+    # and returns them. Capybara raises on unknown options, so this has to
+    # happen before the wrapped call.
+    def extract_options!(options)
+      return {} unless options.is_a?(Hash)
+
+      OPTION_KEYS.each_with_object({}) do |key, extracted|
+        extracted[key] = options.delete(key) if options.key?(key)
+      end
+    end
+
+    # Records one instruction. +action+ names an I18n key under howdoc.actions;
+    # the remaining keyword arguments are interpolated into it. Pass
+    # <tt>html:</tt> instead to supply already-rendered markup, for the rare
+    # step no sentence describes.
+    def record(action = nil, html: nil, arrival: false, nodoc: false, **payload)
+      return nil if nodoc || !recording?
+
+      markup = html || Narrator.call(action, locale: current.locale, **payload)
+      return nil if markup.nil?
+
+      current.new_step(html: markup, arrival:)
+    end
+
+    # Illustrates the step recorded most recently. Separate from +record+
+    # because a screenshot has to be taken while the browser is still on the
+    # page, whereas the sentence can be composed at any time.
+    def capture(page, full_page: false, no_screenshot: false)
+      return nil if no_screenshot || !recording?
+
+      step = current.last_step || current.new_step
+      filename = current.image_filename(step.number)
+
+      Screenshot.capture(
+        page,
+        path: File.join(current.image_dir, filename),
+        height: Howdoc.config.screenshot_height,
+        full_page:
+      )
+
+      step.screenshot = filename
+    end
+
+    # Convenience for the common shape: say what happens, then show it.
+    def record_and_capture(action, page:, options: {}, **payload)
+      step = record(action, nodoc: options[:nodoc], **payload)
+      capture(page, full_page: options[:full_page], no_screenshot: options[:no_screenshot]) if step
+      step
+    end
+  end
+end

data/lib/howdoc/registry.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'fileutils'
+
+module Howdoc
+  # The index, assembled at the end of a run from the guides themselves.
+  #
+  # Tests run in forked workers, so nothing held in memory survives a suite and
+  # the index has to be built from what is on disk. What is on disk is the
+  # guides -- and their markup is not a foreign format to be parsed
+  # defensively, because this gem wrote it. One element carries everything the
+  # index needs.
+  #
+  # That is the entire contract with an overriding template: keep the document
+  # heading in <title>. Everything else the index shows comes from where a file
+  # sits rather than from what is inside it, so there is nothing else to break.
+  module Registry
+    INDEX_FILENAME = 'index.html'
+
+    TITLE = %r{<title[^>]*>(.*?)</title>}mi
+
+    # A heading opens with an identifier when it reads like "1.3. Some title".
+    # The identifier has to carry a digit, so an ordinary sentence beginning
+    # "Mr. Smith" is not mistaken for one.
+    HEADING = /\A([\w.]*\d[\w.]*)\.\s+(.+)\z/m
+
+    # A guide as it appears in the index. It answers to the same readers a live
+    # Howdoc::Document does, so configuration hooks work with either.
+    Record = Struct.new(:locale, :permalink, :heading, :id, :title, keyword_init: true) do
+      def filename
+        "#{permalink}.html"
+      end
+    end
+
+    module_function
+
+    def records(root = Howdoc.config.root)
+      Dir.glob(File.join(root, '*', '*.html')).filter_map { |path| read(path) }
+    end
+
+    def read(path)
+      basename = File.basename(path)
+      return nil if generated_page?(basename)
+
+      heading = title_of(File.read(path))
+      return nil if heading.nil? || heading.empty?
+
+      id, title = split_heading(heading)
+
+      Record.new(
+        locale: File.basename(File.dirname(path)),
+        permalink: File.basename(basename, '.html'),
+        heading:, id:, title:
+      )
+    end
+
+    # The index is not a guide, and neither is a landing page somebody
+    # maintains by hand.
+    def generated_page?(basename)
+      basename == INDEX_FILENAME || Howdoc.config.preserved_files.include?(basename)
+    end
+
+    def title_of(markup)
+      match = markup.match(TITLE)
+      return nil if match.nil?
+
+      CGI.unescapeHTML(match[1]).strip
+    end
+
+    def split_heading(heading)
+      match = heading.match(HEADING)
+      match ? [match[1], match[2]] : [nil, heading]
+    end
+
+    def by_locale(root = Howdoc.config.root)
+      found = records(root).group_by(&:locale)
+      return found if Howdoc.config.locales.nil?
+
+      Howdoc.config.locales.to_h { |locale| [locale.to_s, found.fetch(locale.to_s, [])] }
+    end
+
+    # Builds the index for every locale that produced at least one guide.
+    def write_indexes(root = Howdoc.config.root)
+      Templates.install_assets(File.join(root, 'assets')) if Howdoc.config.install_assets
+
+      by_locale(root).map do |locale, records|
+        Writers::Index.call(locale:, records: sort(records), root:)
+      end
+    end
+
+    def sort(records)
+      records.sort_by { |record| Howdoc.config.sort_key.call(record).to_s }
+    end
+
+    # Removes generated guides while leaving hand-maintained pages in place, so
+    # a run never inherits a guide whose test has since been deleted.
+    #
+    # Only what this gem writes is removed. An output directory usually holds
+    # other things -- a landing page, a stylesheet an application maintains by
+    # hand -- and a cleaner that swept the whole directory would eat them.
+    def clean(root = Howdoc.config.root)
+      Dir.glob(File.join(root, '*')).each do |dir|
+        next unless File.directory?(dir)
+
+        FileUtils.rm_rf(File.join(dir, 'images'))
+
+        Dir.glob(File.join(dir, '*.html')).each do |entry|
+          next if Howdoc.config.preserved_files.include?(File.basename(entry))
+
+          FileUtils.rm_f(entry)
+        end
+      end
+    end
+  end
+end

data/lib/howdoc/screenshot.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # Guides are illustrated, and an illustration is only useful if every picture
+  # in the set has the same proportions. The browser window is therefore sized
+  # deliberately before each capture rather than left wherever the test put it.
+  module Screenshot
+    module_function
+
+    def capture(page, path:, height:, full_page: false)
+      FileUtils.mkdir_p(File.dirname(path))
+
+      width, current_height = page.current_window.size
+      target = full_page ? full_page_height(page) : height
+
+      page.current_window.resize_to(width, target) unless target == current_height
+
+      page.save_screenshot(path, full: true)
+      path
+    end
+
+    def full_page_height(page)
+      page.execute_script('return document.body.scrollHeight;').to_i + 30
+    end
+  end
+end

data/lib/howdoc/step.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # One numbered instruction in a guide: a sentence, optionally an illustration,
+  # and a flag for the steps that mark the reader's arrival on a new page.
+  class Step
+    attr_reader :number
+    attr_accessor :html, :screenshot, :arrival
+
+    def initialize(number:, html: nil, screenshot: nil, arrival: false)
+      @number = number
+      @html = html
+      @screenshot = screenshot
+      @arrival = arrival
+    end
+
+    def empty?
+      html.nil? && screenshot.nil?
+    end
+  end
+end

data/lib/howdoc/tasks.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'howdoc'
+
+namespace :howdoc do
+  desc 'Remove generated guides, leaving hand-maintained pages in place'
+  task :clean do
+    Howdoc.clean
+    puts "Howdoc: cleaned #{Howdoc.config.root}"
+  end
+
+  desc 'Rebuild the index from the manifests already on disk'
+  task :index do
+    written = Howdoc::Registry.write_indexes
+    puts "Howdoc: wrote #{written.size} index file(s)"
+  end
+end

data/lib/howdoc/templates.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'haml'
+require 'fileutils'
+
+module Howdoc
+  # Page chrome lives here, never in the code that records steps. Directories
+  # are searched most-recently-registered first and the gem's own set is always
+  # searched last, so an application overrides one file by mirroring its path
+  # and leaves the rest alone. The layout is borrowed from YARD, which has been
+  # proving it works for well over a decade.
+  module Templates
+    DEFAULT_ROOT = File.expand_path('../../templates', __dir__)
+    DEFAULT_NAME = 'default'
+
+    # Renders a template against a hash of assigns, exposed to the template as
+    # instance variables.
+    class Context
+      def initialize(assigns)
+        @assigns = assigns
+        assigns.each { |name, value| instance_variable_set(:"@#{name}", value) }
+      end
+
+      # Renders another template with the same assigns plus any extras, for
+      # partials that need a single item out of a collection.
+      def render(relative, extra = {})
+        Templates.render(relative, @assigns.merge(extra))
+      end
+    end
+
+    class MissingTemplate < StandardError; end
+
+    module_function
+
+    def search_paths
+      Howdoc.config.template_paths + [DEFAULT_ROOT]
+    end
+
+    # Finds +relative+ (for example "document/html/layout.haml") in the first
+    # search path that has it, falling back to the default template name so a
+    # partial theme only has to carry the files it actually changes.
+    def find(relative, template: DEFAULT_NAME)
+      candidates = search_paths.flat_map do |root|
+        [File.join(root, template, relative), File.join(root, DEFAULT_NAME, relative)]
+      end
+
+      candidates.uniq.find { |path| File.file?(path) } ||
+        raise(MissingTemplate, "no template found for #{relative.inspect} in #{search_paths.inspect}")
+    end
+
+    def render(relative, assigns = {})
+      compiled(find(relative)).render(Context.new(assigns))
+    end
+
+    # Haml compiles a template into Ruby once and then renders it; a suite that
+    # writes a hundred guides should pay for that compilation once.
+    def compiled(path)
+      @compiled ||= {}
+      @compiled[path] ||= Haml::Template.new(path)
+    end
+
+    # Copies everything under an "assets" directory of every search path into
+    # the output directory, later paths first so an application's file wins.
+    def install_assets(into)
+      FileUtils.mkdir_p(into)
+
+      search_paths.reverse_each do |root|
+        assets = File.join(root, DEFAULT_NAME, 'assets')
+        next unless File.directory?(assets)
+
+        Dir.glob(File.join(assets, '*')).each { |file| FileUtils.cp(file, into) }
+      end
+    end
+  end
+end

data/lib/howdoc/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Howdoc
+  VERSION = '0.1.0'
+end

data/lib/howdoc/writers.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Howdoc
+  # One recorded document, several possible outputs. Adding a format is adding a
+  # class here, not rewriting the engine -- the same separation rspec_api_
+  # documentation used to turn one test run into HTML and half a dozen API
+  # description languages.
+  module Writers
+    module_function
+
+    def registry
+      @registry ||= { html: Html }
+    end
+
+    def register(name, writer)
+      registry[name.to_sym] = writer
+    end
+
+    def fetch(name)
+      registry.fetch(name.to_sym) do
+        raise ArgumentError, "unknown Howdoc format #{name.inspect}, known: #{registry.keys.inspect}"
+      end
+    end
+
+    def write(document)
+      Howdoc.config.formats.map { |format| fetch(format).call(document) }
+    end
+
+    # Writes the illustrated guide a reader actually opens.
+    class Html
+      def self.call(document)
+        FileUtils.mkdir_p(document.dir)
+        markup = Templates.render(
+          'document/html/layout.haml',
+          document:, config: Howdoc.config
+        )
+        File.write(document.path('html'), markup)
+        document.path('html')
+      end
+    end
+
+    # Writes one index per locale, from the guides the run just produced.
+    class Index
+      def self.call(locale:, records:, root: Howdoc.config.root)
+        dir = File.join(root, locale.to_s)
+        FileUtils.mkdir_p(dir)
+
+        markup = Templates.render(
+          'index/html/layout.haml',
+          locale:, records:, config: Howdoc.config
+        )
+        path = File.join(dir, 'index.html')
+        File.write(path, markup)
+        path
+      end
+    end
+  end
+end

data/lib/howdoc.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'i18n'
+require 'fileutils'
+
+require_relative 'howdoc/version'
+require_relative 'howdoc/configuration'
+require_relative 'howdoc/narrator'
+require_relative 'howdoc/step'
+require_relative 'howdoc/document'
+require_relative 'howdoc/screenshot'
+require_relative 'howdoc/recorder'
+require_relative 'howdoc/templates'
+require_relative 'howdoc/writers'
+require_relative 'howdoc/registry'
+
+# Generates end-user documentation from Capybara system tests.
+#
+# A test that already drives the browser knows every step a person would take.
+# Howdoc listens to those steps, narrates them, photographs the result and
+# writes an illustrated guide. Because the guide comes out of a test that has
+# to pass, it cannot quietly drift away from the application it describes.
+module Howdoc
+  LOCALES_ROOT = File.expand_path('../config/locales', __dir__)
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield(config)
+      install_locales
+      config
+    end
+
+    def reset!
+      @config = nil
+      Recorder.current = nil
+      Narrator.reset_missing_keys
+    end
+
+    def enabled?
+      config.enabled?
+    end
+
+    # Adds the gem's own English and then any translations the application
+    # registered, so an application only has to translate what it wants to say
+    # differently.
+    def install_locales
+      globs = [File.join(LOCALES_ROOT, '*.yml')] + config.locale_paths
+      added = globs.flat_map { |glob| Dir.glob(glob) } - I18n.load_path
+
+      return if added.empty?
+
+      I18n.load_path.concat(added)
+      I18n.backend.reload! if I18n.backend.respond_to?(:reload!)
+    end
+
+    # Begins a guide. Everything recorded until #finish belongs to it.
+    def start(id: nil, title: nil, locale: I18n.locale, permalink: nil, intro: nil)
+      return nil unless enabled?
+      return nil if title.to_s.strip.empty?
+
+      Recorder.current = Document.new(id:, title:, locale:, permalink:, intro:)
+    end
+
+    # Ends the guide and writes it out. Called even when the test failed, so a
+    # broken step leaves visible evidence instead of no page at all.
+    def finish
+      document = Recorder.current
+      Recorder.current = nil
+      return nil if document.nil? || document.steps.empty?
+
+      Writers.write(document)
+      document
+    end
+
+    def current
+      Recorder.current
+    end
+
+    def record(...)
+      Recorder.record(...)
+    end
+
+    def capture(...)
+      Recorder.capture(...)
+    end
+
+    def record_and_capture(...)
+      Recorder.record_and_capture(...)
+    end
+
+    def extract_options!(...)
+      Recorder.extract_options!(...)
+    end
+
+    # Assembles the index from the manifests. Run once, after the whole suite.
+    def finalize
+      return [] unless enabled?
+
+      Registry.write_indexes
+    ensure
+      warn_about_missing_translations
+    end
+
+    def clean
+      Registry.clean
+    end
+
+    def warn_about_missing_translations
+      keys = Narrator.missing_keys
+      return if keys.empty?
+
+      warn "\nHowdoc: #{keys.size} untranslated step(s), the guides are missing those instructions:"
+      keys.sort.each { |key| warn "  #{key}" }
+    end
+  end
+end