Process pages for actions
With actionable-docs, each action gets a page a product manager or a support lead can read. It covers what the action does, in what order, why it can stop, and what happens after. The page is Markdown with one Mermaid flowchart, and it’s built from the declarations and the descriptions you already wrote. Nothing runs the action.
gem 'actionable-docs'A page from an action
Section titled “A page from an action”When the action and its parts have a desc, the page uses those words. Anything without one gets words made from its name.
require 'actionable/docs'
module Bindery class SewSignatures < Actionable::Action desc 'Sews the folded sections of a book together.'
input do required :sections, :integer, desc: 'How many folded sections' optional :thread_colour, :string end
fails :paper_torn, 'a section tore at the fold', retry: false skips :already_sewn, desc: 'The block came in sewn'
step :punch_holes, desc: 'Punch the sewing holes' case_step :binding, desc: 'The binding style' do on 'coptic', :sew_chain_stitch on %w[case long], :sew_on_tapes end step :glue_spine, unless: :loose_leaf?
on_success :log_job
private
def binding = 'coptic' def loose_leaf? = false def punch_holes = nil def sew_chain_stitch = nil def sew_on_tapes = nil def glue_spine = nil def log_job = nil endend
page = Actionable::Docs.markdown(Bindery::SewSignatures)
Actionable::Docs.title(Bindery::SewSignatures) # => "Sew signatures"Actionable::Docs.path_for(Bindery::SewSignatures) # => "bindery/sew_signatures.md"page.include?("2. Depending on the binding style:\n - coptic: Sew chain stitch\n - case or long: Sew on tapes") # => truepage.include?('3. Glue spine (skipped when loose leaf)') # => truepage.include?('- When it succeeds: Log job') # => trueWhat a page holds
Section titled “What a page holds”In this order, leaving out any section that would be empty:
- The title, made from the class’s last name segment (
SewSignaturesgives “Sew signatures”), and the action’sdesc. - The flowchart.
- Steps: numbered, with guards in words (
only when ...,skipped when ...) and a case step’s branches nested under it. - It can stop because and It can finish early because: each declared failure and skip with its words and its code in backticks, plus a note when its metadata says
retry: trueorretry: false. - What happens after: the hooks, in a fixed order.
- What it needs and What it produces: the input and output fields, with their
desc:and whether they’re required. - Also runs: actions found in the source, as links.
- A last line saying the page is generated, so readers edit the action instead.
The page names no class. A child action shows as a link to its own page.
The flowchart
Section titled “The flowchart”The happy path runs top to bottom from Start to Done. A guarded step gets a yes/no decision before it, and a case step becomes a decision with one edge per branch, plus anything else. A child action is one box with a link to its page, and it never opens up inline, so a page stays short.
Every declared failure and skip hangs off Start with the label any step. That’s honest about what describe knows: it doesn’t say which step can end with which code.
Writing and checking pages
Section titled “Writing and checking pages”Every call needs a named class, since the title and the path come from its name: an anonymous Class.new(Actionable::Action) raises ArgumentError.
Actionable::Docs.write(actions, dir:) writes each page under dir and returns the paths. Actionable::Docs.stale(actions, dir:) returns the pages that are missing or differ from fresh ones, and writes nothing.
For a Rakefile:
require 'actionable/docs/tasks'
Actionable::Docs::Tasks.define(actions: -> { [Bindery::SewSignatures] }, dir: 'docs/actions')rake actionable:docs writes the pages. rake actionable:docs:check fails and lists the stale pages when they differ, so run it in CI and the pages can’t drift from the code. Pass actions: as a lambda so your app loads its code first. Only the actions you list get pages.
What isn’t covered yet
Section titled “What isn’t covered yet”- The headings are fixed English.
- There’s no JSON output, Rails view or per-step code list.
- A large action gives a large chart, and nothing collapses it.
See also
Section titled “See also”- Batches and introspection:
describe, the source of every page - LLM and MCP tools
- How adapters work
FieldStruct, Actionable and their adapters are open source under the MIT license.