howdoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 02cc27d9848b0932cc7ba10c66b8e5682c955071f2cde03f27e6c9061c52d82c
+  data.tar.gz: 1bed4d6da3860c0ea8ac1f3f680218f24941f45fbb7d8e3b0699085e70588811
+SHA512:
+  metadata.gz: 72e52519fec7d24abdb8765aa146702ef053a627fd87e4b40e1ff77775ba69ed626db5250accbb307719bbfee68a7f12e8d1fac6d966a0ab05df9859a1b38326
+  data.tar.gz: 70208bdc3b1557985b69bbdceb70ade90a91c39b9063412ed922df7cd1cae26e5629875dd1f66a16277364af39d49eff10ede8df80695c678a1792675f0f0b42

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0
+
+First release. Extracted from a working in-house documentation helper that had
+been generating user guides from a Rails application's Capybara system tests.
+
+- Narrates Capybara actions into prose through I18n, so the vocabulary is
+  translatable and no sentence is hardcoded in the engine. English and Estonian
+  are included.
+- Captures a screenshot per interesting step.
+- Writes an illustrated HTML guide per document.
+- Builds an index across all generated guides, read back from the pages
+  themselves at the end of the run.
+- Templates are Haml and overridable per directory, so an application supplies
+  its own page chrome without forking the gem.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Priit Tark
+
+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

@@ -0,0 +1,221 @@
+# Howdoc
+
+Generate end-user documentation from your Capybara system tests.
+
+A system test already knows every step a person would take through your
+application: which link they click, what they type, what they should see next.
+Howdoc listens to those steps, narrates them in prose, photographs the browser
+along the way, and writes an illustrated guide.
+
+Because the guide is produced by a test that has to pass, it cannot quietly
+drift away from the application it describes. When the workflow changes, either
+the guide changes with it or the test goes red.
+
+```
+test 'should add a claim', doc: '1.3', permalink: 'how_to_add_a_claim' do
+  sign_in :user
+
+  tap_menu ['Contacts', 'Claims']
+  tap_link 'New'
+
+  fill_in 'Ref', with: 'TestREF'
+  select 'Test', from: 'Contact'
+  click_button 'Save'
+
+  assert_text 'TestREF'
+end
+```
+
+becomes a page titled *1.3. How to add a claim?* with numbered instructions and
+a screenshot at each point where the reader arrives somewhere new.
+
+## Installation
+
+```ruby
+group :test do
+  gem 'howdoc'
+end
+```
+
+## Configuration
+
+```ruby
+Howdoc.configure do |config|
+  config.root    = 'public/docs'          # where guides are written
+  config.enabled = ENV['DOC'].present?    # off unless asked for
+  config.host    = 'example.com'          # the address a reader should open
+  config.formats = %i[html]
+
+  config.register_locale_path 'test/howdoc/locales/*.yml'
+  config.register_template_path 'test/howdoc/templates'
+end
+```
+
+Nothing above has a sensible universal default except the formats, which is why
+none of it is baked into the engine.
+
+## Wiring it into a Minitest suite
+
+Howdoc does not guess how your suite starts and finishes a test. The wiring is
+short and belongs in your own test case, where you can see it:
+
+```ruby
+require 'howdoc/capybara_actions'
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  include Howdoc::CapybaraActions   # include last: each wrapper ends in super
+
+  setup do
+    Howdoc.start(
+      id: metadata[:doc],
+      permalink: metadata[:permalink],
+      intro: metadata[:intro],
+      title: "How to #{metadata[:description]}?",
+      locale: I18n.locale
+    )
+  end
+
+  teardown { Howdoc.finish }
+end
+```
+
+`Howdoc.finish` is called in `teardown` rather than after a successful
+assertion, so a test that breaks halfway still leaves a partial guide showing
+exactly how far the reader would have got.
+
+Once the whole run is over, build the index:
+
+```ruby
+Howdoc::MinitestIntegration.install_at_exit!
+```
+
+or call `Howdoc.finalize` from wherever your suite already reports completion.
+Tests run in forked workers, so the index is assembled at the end from the
+manifest each guide leaves on disk, not from anything held in memory.
+
+## What ends up in a guide
+
+Howdoc wraps the Capybara verbs a person would recognise as an instruction:
+`visit`, `fill_in`, `select`, `check`, `uncheck`, `choose`, `click_button`,
+`click_link`, `click_on`, `attach_file` and `assert_text`. Everything else your
+test does happens silently.
+
+Each of them accepts four extra options, removed before the call reaches
+Capybara:
+
+| Option | Effect |
+| --- | --- |
+| `nodoc: true` | leave this action out of the guide |
+| `screenshot: true` | illustrate an action that normally is not illustrated |
+| `no_screenshot: true` | skip the illustration |
+| `full_page: true` | capture the whole scrollable page |
+
+By default `visit` and `assert_text` are illustrated and the action verbs are
+not, on the grounds that a picture is worth showing when the reader arrives
+somewhere, not every time they press a button.
+
+## Your own helpers
+
+Real suites have helpers Capybara has no verb for -- a custom editor, a menu
+widget, a checkbox drawn as something else. Howdoc cannot know about those, so
+it exposes the same recording API its own wrappers use:
+
+```ruby
+def choose_from_fancy_menu(*path)
+  Howdoc.record(:fancy_menu, path: path.join(' → '))
+  Howdoc.capture(page)
+
+  within('#navbar') { path.each { |item| click_link(item, nodoc: true) } }
+end
+```
+
+`Howdoc.record` is a no-op when documentation is switched off, so helpers need
+no guards. Pass `html:` instead of an action name for the rare step no sentence
+describes.
+
+Three actions come translated even though no wrapper records them, because
+almost every suite ends up writing a helper that needs one: `menu` (a `path`),
+`fill_in_editor` (a `value`) and `sign_in_required` (a `text`).
+
+## Wording
+
+Every sentence is an I18n key under `howdoc.actions`, so the engine contains no
+prose of its own. English and Estonian ship with the gem, complete; an
+application needs no translation file of its own unless it changes the wording,
+adds a language, or records an action of its own invention:
+
+```yaml
+fi:
+  howdoc:
+    actions:
+      click_button: Paina painiketta <strong>"%{locator}"</strong>.
+```
+
+Interpolated values are HTML-escaped, the translations carry the markup.
+
+Field names are humanised before they reach a translation: `user_email` becomes
+"email", because a reader does not know your schema. Give a field a name of its
+own by translating `howdoc.fields.<locator>`, or replace the whole convention:
+
+```ruby
+config.field_label { |locator| MyLabels.for(locator) }
+```
+
+Any key that is used but not translated is reported at the end of the run rather
+than leaving a silent hole in the guide.
+
+## Templates
+
+Page chrome lives in templates, never in the code that records steps, so
+restyling a guide does not mean running a browser suite again.
+
+Templates are Haml, looked up as
+`<registered path>/default/<type>/<format>/<file>`, searched most recently
+registered first, with the gem's own set searched last. To change only the page
+shell, mirror that one path:
+
+```
+test/howdoc/templates/default/document/html/layout.haml
+```
+
+Everything else keeps coming from the gem. The arrangement is borrowed from
+YARD, which has been proving it works for well over a decade.
+
+Assigns arrive as instance variables (`@document`, `@records`, `@config`) and
+`render` pulls in a partial. Haml escapes `=` output, so a narrated sentence --
+which carries its own markup and whose values were escaped when the step was
+recorded -- is written with `!=`.
+
+An overriding document layout has exactly one obligation: keep the heading in
+`<title>`. That is what the index reads. A page without one is left out of the
+index rather than listed blank. Everything else the index shows -- which locale
+a guide belongs to, what it links to -- comes from where the file sits.
+
+## Output
+
+```
+public/docs/
+  assets/howdoc.css
+  en/
+    index.html
+    how_to_add_a_claim.html
+    images/how_to_add_a_claim_4.png
+```
+
+A guide is a page and nothing else. The index is built at the end of the run by
+reading those pages back: tests run in forked workers, so nothing survives in
+memory, and the pages are the only record of what was produced. Their markup is
+not a foreign format to be parsed defensively -- this gem wrote it.
+
+## Rake tasks
+
+```ruby
+require 'howdoc/tasks'
+```
+
+* `howdoc:clean` — remove generated guides, leaving `config.preserved_files` alone
+* `howdoc:index` — rebuild the index from manifests already on disk
+
+## Licence
+
+MIT.

data/config/locales/howdoc.en.yml

@@ -0,0 +1,24 @@
+en:
+  howdoc:
+    actions:
+      assert_text: You should now see <strong>"%{text}"</strong>.
+      attach_file: Attach a file to <strong>%{field}</strong>.
+      check: Tick <strong>"%{field}"</strong>.
+      choose: Choose <strong>"%{field}"</strong>.
+      click_button: Press the <strong>"%{locator}"</strong> button.
+      click_link: Click the <strong>"%{locator}"</strong> link.
+      click_on: Click <strong>"%{locator}"</strong>.
+      fill_in: Fill in <strong>%{field}</strong> with <strong>"%{value}"</strong>.
+      fill_in_editor: Fill the text editor with <strong>"%{value}"</strong>.
+      fill_in_email: Enter an email address, for example <strong>"%{value}"</strong>.
+      fill_in_password: Enter a password, for example <strong>"%{value}"</strong>.
+      menu: 'Click menu items: <strong>"%{path}"</strong>.'
+      select: Select <strong>"%{value}"</strong> from <strong>%{field}</strong>.
+      sign_in_required: Please log in to the system to access <strong>"%{text}"</strong>.
+      uncheck: Clear the <strong>"%{field}"</strong> tick.
+      visit: Open <strong>%{url}</strong> in your browser.
+    document:
+      follow_steps: 'Follow these steps:'
+    index:
+      empty: No guides have been generated yet.
+      title: Guides

data/config/locales/howdoc.et.yml

@@ -0,0 +1,24 @@
+et:
+  howdoc:
+    actions:
+      assert_text: Näete teksti <strong>"%{text}"</strong>.
+      attach_file: Lisa fail väljale <strong>%{field}</strong>.
+      check: Lisa linnuke <strong>"%{field}"</strong>.
+      choose: Vali <strong>"%{field}"</strong>.
+      click_button: Vajuta nupule <strong>"%{locator}"</strong>.
+      click_link: Vajuta lingile <strong>"%{locator}"</strong>.
+      click_on: Klõpsa <strong>"%{locator}"</strong>.
+      fill_in: Sisesta näiteks <strong>"%{value}"</strong>.
+      fill_in_editor: Sisesta tekstiredaktorisse näiteks <strong>"%{value}"</strong>.
+      fill_in_email: Sisesta eposti aadress, näiteks <strong>"%{value}"</strong>.
+      fill_in_password: Sisesta parool, näiteks <strong>"%{value}"</strong>.
+      menu: 'Vali menüüs: <strong>"%{path}"</strong>.'
+      select: Vali <strong>"%{value}"</strong> hüpikmenüüst "%{field}".
+      sign_in_required: 'Palun logige süsteemi sisse, et pääseda rakenduse keskkonda: <strong>"%{text}"</strong>.'
+      uncheck: Eemalda linnuke <strong>"%{field}"</strong>.
+      visit: Palun sisesta <strong>%{url}</strong> oma brauserisse.
+    document:
+      follow_steps: 'Palun jälgige järgnevaid samme:'
+    index:
+      empty: Ühtegi juhendit ei ole veel loodud.
+      title: Juhendid

data/lib/howdoc/capybara_actions.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'howdoc'
+
+module Howdoc
+  # Wraps the Capybara verbs a person would recognise as an instruction, so an
+  # ordinary test narrates itself. Include it after any other module that wraps
+  # the same verbs -- Ruby searches the most recently included module first, and
+  # each wrapper here ends in +super+.
+  #
+  # Every wrapper accepts four extra options, which are removed before the call
+  # reaches Capybara:
+  #
+  #   nodoc:         leave this action out of the guide entirely
+  #   screenshot:    illustrate this action even though it normally is not
+  #   no_screenshot: do not illustrate this action even though it normally is
+  #   full_page:     capture the whole scrollable page, not one screenful
+  #
+  # Anything the application does that Capybara has no verb for is recorded by
+  # calling Howdoc.record directly from the application's own helper.
+  module CapybaraActions
+    def visit(visit_uri, **options)
+      doc = Howdoc.extract_options!(options)
+      result = super(visit_uri)
+
+      narrate(:visit, doc, capture: true, url: displayed_url(visit_uri))
+      result
+    end
+
+    def fill_in(locator = nil, with:, currently_with: nil, fill_options: {}, **options)
+      doc = Howdoc.extract_options!(options)
+      label = howdoc_field_label(locator)
+
+      narrate(fill_in_action(label), doc, field: label, value: with)
+
+      super(locator, with:, currently_with:, fill_options:, **options)
+    end
+
+    def select(value = nil, from: nil, **options)
+      doc = Howdoc.extract_options!(options)
+
+      narrate(:select, doc, value:, field: howdoc_field_label(from))
+
+      super(value, from:, **options)
+    end
+
+    def check(locator = nil, **options)
+      doc = Howdoc.extract_options!(options)
+
+      narrate(:check, doc, field: howdoc_field_label(locator))
+
+      super(locator, **options)
+    end
+
+    def uncheck(locator = nil, **options)
+      doc = Howdoc.extract_options!(options)
+
+      narrate(:uncheck, doc, field: howdoc_field_label(locator))
+
+      super(locator, **options)
+    end
+
+    def choose(locator = nil, **options)
+      doc = Howdoc.extract_options!(options)
+
+      narrate(:choose, doc, field: howdoc_field_label(locator))
+
+      super(locator, **options)
+    end
+
+    def click_button(locator = nil, **options)
+      doc = Howdoc.extract_options!(options)
+
+      narrate(:click_button, doc, locator:)
+
+      super(locator, **options)
+    end
+
+    def click_link(locator = nil, **options)
+      doc = Howdoc.extract_options!(options)
+
+      narrate(:click_link, doc, locator:)
+
+      super(locator, **options)
+    end
+
+    def click_on(locator = nil, **options)
+      doc = Howdoc.extract_options!(options)
+
+      narrate(:click_on, doc, locator:)
+
+      super(locator, **options)
+    end
+
+    # rubocop:disable Style/OptionalArguments
+    def attach_file(locator = nil, paths, make_visible: nil, **options)
+      doc = Howdoc.extract_options!(options)
+
+      narrate(:attach_file, doc, field: howdoc_field_label(locator))
+
+      super(locator, paths, make_visible:, **options)
+    end
+    # rubocop:enable Style/OptionalArguments
+
+    # The one assertion that is also an instruction: it is how a guide tells the
+    # reader they have arrived somewhere and what they should see there.
+    def assert_text(locator, **options)
+      doc = Howdoc.extract_options!(options)
+      result = super(locator, **options)
+
+      narrate(:assert_text, doc, capture: true, arrival: true, text: locator)
+      result
+    end
+
+    private
+
+    def howdoc_field_label(locator)
+      Howdoc::Narrator.field_label(locator, locale: howdoc_locale)
+    end
+
+    def howdoc_locale
+      Howdoc.current&.locale || I18n.locale
+    end
+
+    def fill_in_action(label)
+      case label.to_s
+      when 'email' then :fill_in_email
+      when 'password' then :fill_in_password
+      else :fill_in
+      end
+    end
+
+    # A guide tells the reader to open the application's real address, not the
+    # ephemeral host and port the test server happens to be listening on.
+    def displayed_url(visit_uri)
+      host = Howdoc.config.host
+      host.nil? ? visit_uri.to_s : "https://#{host}#{visit_uri}"
+    end
+
+    def narrate(action, doc_options, capture: false, arrival: false, **payload)
+      step = Howdoc.record(action, arrival:, nodoc: doc_options[:nodoc], **payload)
+      return nil if step.nil?
+
+      illustrate = doc_options.fetch(:screenshot, capture)
+      return step unless illustrate
+
+      Howdoc.capture(
+        page,
+        full_page: doc_options[:full_page] || false,
+        no_screenshot: doc_options[:no_screenshot] || false
+      )
+      step
+    end
+  end
+end

data/lib/howdoc/configuration.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # Everything an application is allowed to decide: where guides are written,
+  # what they are called, which templates dress them and how the index is
+  # ordered. The engine itself holds no application knowledge, so anything that
+  # would otherwise be hardcoded belongs here.
+  class Configuration
+    # Directory the generated guides are written into, relative to the working
+    # directory unless given as an absolute path.
+    attr_accessor :root
+
+    # Guides are only generated when this is true. Keep it tied to an
+    # environment variable so an ordinary test run stays fast.
+    attr_accessor :enabled
+
+    # Public host name of the documented application. It appears in the prose
+    # for +visit+, where telling the reader to open "localhost:9200" would be
+    # useless.
+    attr_accessor :host
+
+    # Writers to run for every finished document, in order.
+    attr_accessor :formats
+
+    # Locales to build an index for. Left nil, only the locales that actually
+    # produced a guide get one, which means a run in a single language quietly
+    # drops the other languages' indexes. Naming them keeps every index in
+    # place, empty ones included.
+    attr_accessor :locales
+
+    # Screenshots are taken at this height unless the step asked for a full
+    # page, so that guides do not mix wildly different image proportions.
+    attr_accessor :screenshot_height
+
+    # Files in the output directory that the clean task must leave alone,
+    # typically hand-maintained landing pages.
+    attr_accessor :preserved_files
+
+    # Whether the templates' assets directory is copied into the output. An
+    # application whose templates link its own stylesheets turns this off.
+    attr_accessor :install_assets
+
+    # Directories searched for templates, most recently registered first. The
+    # gem's own directory is always searched last, so an application overrides
+    # a single file by mirroring its path rather than copying the whole set.
+    attr_reader :template_paths
+
+    # Globs of translation files to add to I18n's load path. The gem's English
+    # is loaded first so an application only translates what it wants to change.
+    attr_reader :locale_paths
+
+    def initialize
+      @root = 'doc/howdoc'
+      @enabled = false
+      @host = nil
+      @formats = %i[html]
+      @locales = nil
+      @screenshot_height = 940
+      @preserved_files = %w[index.html .keep]
+      @install_assets = true
+      @template_paths = []
+      @locale_paths = []
+      @field_label = nil
+      @sort_key = nil
+      @group_label = nil
+    end
+
+    def register_template_path(path)
+      @template_paths.unshift(path.to_s)
+    end
+
+    def register_locale_path(glob)
+      @locale_paths << glob.to_s
+    end
+
+    # How a form field locator becomes something a reader recognises. The
+    # default turns +user_email+ into "email", which suits Rails' own naming.
+    # Applications with their own conventions replace it wholesale.
+    def field_label(&block)
+      return @field_label = block if block
+
+      @field_label ||= ->(locator) { Howdoc::Narrator.humanize_locator(locator) }
+    end
+
+    # Sorts documents in the index. Receives a Howdoc::Registry::Record.
+    def sort_key(&block)
+      return @sort_key = block if block
+
+      @sort_key ||= ->(record) { record.heading.to_s }
+    end
+
+    # Names the index section a document belongs under, or nil for no section.
+    # Receives a Howdoc::Registry::Record, so it decides from the heading, the
+    # identifier or the file name -- there is nowhere else for a section to
+    # come from once a guide is a page like any other.
+    def group_label(&block)
+      return @group_label = block if block
+
+      @group_label ||= ->(_record) {}
+    end
+
+    def enabled?
+      !!@enabled
+    end
+  end
+end

data/lib/howdoc/document.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # One guide: the identity a test gave it, plus the steps recorded while that
+  # test ran. A document collects everything in memory and is written out once,
+  # so a writer always sees the whole guide rather than a half-built page.
+  class Document
+    # Letters that carry no accent to strip: they are their own character, so
+    # Unicode decomposition leaves them untouched and a filename filter would
+    # otherwise drop them entirely.
+    INDIVISIBLE = {
+      'ß' => 'ss', 'æ' => 'ae', 'œ' => 'oe', 'ø' => 'o',
+      'đ' => 'd', 'ð' => 'd', 'ł' => 'l', 'þ' => 'th'
+    }.freeze
+
+    attr_reader :id, :permalink, :title, :intro, :locale, :steps
+
+    def initialize(id:, title:, locale:, permalink: nil, intro: nil)
+      @id = id
+      @title = title
+      @locale = locale.to_sym
+      @permalink = permalink
+      @intro = intro
+      @steps = []
+      @counter = 0
+    end
+
+    def slug
+      @slug ||= (permalink || slugify(title)).to_s
+    end
+
+    def heading
+      id.nil? ? title : "#{id}. #{title}"
+    end
+
+    def new_step(**attributes)
+      @counter += 1
+      step = Step.new(number: @counter, **attributes)
+      steps << step
+      step
+    end
+
+    def last_step
+      steps.last
+    end
+
+    def dir
+      File.join(Howdoc.config.root, locale.to_s)
+    end
+
+    def image_dir
+      File.join(dir, 'images')
+    end
+
+    def path(extension)
+      File.join(dir, "#{slug}.#{extension}")
+    end
+
+    def image_filename(number)
+      "#{slug}_#{number}.png"
+    end
+
+    private
+
+    # Deliberately not ActiveSupport's parameterize: the engine has no business
+    # dragging Rails into a project that only wanted a documentation generator.
+    #
+    # Accents are decomposed and their marks dropped rather than deleted whole,
+    # so an Estonian title turns into "kuidas_lisada_noue" instead of the
+    # unreadable "kuidas_lisada_n_ue" a plain ASCII filter would leave behind.
+    def slugify(string)
+      string
+        .to_s
+        .downcase
+        .gsub(/[#{INDIVISIBLE.keys.join}]/, INDIVISIBLE)
+        .unicode_normalize(:nfd)
+        .gsub(/\p{Mn}/, '')
+        .downcase
+        .gsub(/[^a-z0-9]+/, '_')
+        .gsub(/\A_+|_+\z/, '')
+    end
+  end
+end

data/lib/howdoc/minitest.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'minitest'
+require 'howdoc'
+
+module Howdoc
+  # Optional convenience for Minitest suites. The gem deliberately does not try
+  # to guess how a project starts and finishes a test, because that wiring is
+  # six readable lines in the project's own test case and any guess would be
+  # wrong somewhere. All this offers is the one hook that has no good place in
+  # a test case: assembling the index once the whole run is over.
+  module MinitestIntegration
+    class << self
+      def install_at_exit!
+        return if @installed
+
+        @installed = true
+        ::Minitest.after_run { Howdoc.finalize }
+      end
+    end
+  end
+end