actionable-docs 1.0.0.pre1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +6 -0
- data/LICENSE.txt +21 -0
- data/README.md +86 -0
- data/lib/actionable/docs/flowchart.rb +95 -0
- data/lib/actionable/docs/page.rb +109 -0
- data/lib/actionable/docs/tasks.rb +43 -0
- data/lib/actionable/docs/version.rb +10 -0
- data/lib/actionable/docs/words.rb +97 -0
- data/lib/actionable/docs.rb +76 -0
- data/sig/actionable-docs.rbs +153 -0
- metadata +76 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 1034dc9692667f5b45a2312d121a57c81a875f2f9e32e8d5fff26264b3be4a32
|
|
4
|
+
data.tar.gz: a30dfd18d1a27db99a31efee79c9cad44a60fbb4b39f1230989680d0bd5680e0
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 41c3d6fcb31e50ed9a5fbc601d83eeb1cee6ea7ce7bfdadc8330c64d514b18edcfb208bc6d00e56e9c55a19ef3933ce1d1865d006bad6bc111da560554d9e5de
|
|
7
|
+
data.tar.gz: 5d0944fee20260133da4e9c9a14eb99cea32abd61940164d61224986384395f0cccb3732212d6dccc7c96adf74f9c49bf09a69f90818a9b6ccaab60d5209a2fc
|
data/CHANGELOG.md
ADDED
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Adrian Madrid
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# actionable-docs
|
|
2
|
+
|
|
3
|
+
Turn an [actionable-rb](../../gems/actionable) action into a page someone outside the code can read: what it does,
|
|
4
|
+
in what order, why it can stop, and what happens after. The page is Markdown with one Mermaid flowchart, built from
|
|
5
|
+
the action's declarations and descriptions. A rake task writes the pages, and a check task fails when they drift.
|
|
6
|
+
|
|
7
|
+
```ruby
|
|
8
|
+
gem 'actionable-docs'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Version `1.0.0.pre1`. Ruby 3.3 or newer. Load it with `require 'actionable/docs'`.
|
|
12
|
+
|
|
13
|
+
## A page from an action
|
|
14
|
+
|
|
15
|
+
Give the action and its parts a `desc`, and the page uses those words. Anything without one gets words made from its
|
|
16
|
+
name.
|
|
17
|
+
|
|
18
|
+
```ruby run
|
|
19
|
+
require 'actionable/docs'
|
|
20
|
+
|
|
21
|
+
module Framing
|
|
22
|
+
class MountPrint < Actionable::Action
|
|
23
|
+
desc 'Mounts a customer print behind glass.'
|
|
24
|
+
|
|
25
|
+
input { required :width_cm, :integer, desc: 'Width of the print' }
|
|
26
|
+
|
|
27
|
+
fails :glass_chipped, 'the glass pane is chipped', retry: false
|
|
28
|
+
|
|
29
|
+
step :cut_mat, desc: 'Cut the mat to size'
|
|
30
|
+
step :fit_glass, if: :glass_ordered?
|
|
31
|
+
|
|
32
|
+
private
|
|
33
|
+
|
|
34
|
+
def glass_ordered? = true
|
|
35
|
+
def cut_mat = nil
|
|
36
|
+
def fit_glass = nil
|
|
37
|
+
end
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
page = Actionable::Docs.markdown(Framing::MountPrint)
|
|
41
|
+
|
|
42
|
+
Actionable::Docs.title(Framing::MountPrint) # => "Mount print"
|
|
43
|
+
Actionable::Docs.path_for(Framing::MountPrint) # => "framing/mount_print.md"
|
|
44
|
+
page.lines.first # => "# Mount print\n"
|
|
45
|
+
page.include?('2. Fit glass (only when glass ordered)') # => true
|
|
46
|
+
page.include?('- **Glass chipped**: the glass pane is chipped _(don\'t retry)_ `glass_chipped`') # => true
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The page has, in order: the title and description, the flowchart, the numbered steps, "It can stop because" and
|
|
50
|
+
"It can finish early because" (the declared failures and skips), "What happens after" (the hooks), "What it needs"
|
|
51
|
+
and "What it produces" (the input and output fields), and "Also runs" for actions found in the source, then a
|
|
52
|
+
line saying the page is generated. Empty sections are left out.
|
|
53
|
+
|
|
54
|
+
In the chart, a child action is one box that links to its own page; it never opens up inline. A guard is a
|
|
55
|
+
decision, and a case step is a decision with one edge per branch. Failures and skips hang off Start, since
|
|
56
|
+
`describe` doesn't say which step ends with which code.
|
|
57
|
+
|
|
58
|
+
## Writing and checking pages
|
|
59
|
+
|
|
60
|
+
Every call needs a named class: an anonymous `Class.new(Actionable::Action)` raises `ArgumentError`.
|
|
61
|
+
`Docs.write(actions, dir:)` writes each page and returns the paths. `Docs.stale(actions, dir:)` returns the pages
|
|
62
|
+
that are missing or out of date, and writes nothing.
|
|
63
|
+
|
|
64
|
+
For a Rakefile:
|
|
65
|
+
|
|
66
|
+
```ruby
|
|
67
|
+
require 'actionable/docs/tasks'
|
|
68
|
+
|
|
69
|
+
Actionable::Docs::Tasks.define(actions: -> { [Framing::MountPrint] }, dir: 'docs/actions')
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
That gives you `rake actionable:docs` (write the pages) and `rake actionable:docs:check` (fail, listing the stale
|
|
73
|
+
pages, when they differ from fresh ones; run it in CI). Pass `actions:` as a lambda so your app's code loads first.
|
|
74
|
+
Only the actions you list get pages.
|
|
75
|
+
|
|
76
|
+
## What is and is not covered
|
|
77
|
+
|
|
78
|
+
- Headings are fixed English.
|
|
79
|
+
- No JSON output, no Rails view, and no per-step codes yet.
|
|
80
|
+
- A large action gives a large chart; nothing collapses it.
|
|
81
|
+
|
|
82
|
+
Signatures are in `sig/`.
|
|
83
|
+
|
|
84
|
+
## Docs
|
|
85
|
+
|
|
86
|
+
The guide on the docs site, with every example run in CI: https://gliders-rb.github.io/adapters/process-docs/
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Actionable
|
|
4
|
+
module Docs
|
|
5
|
+
# The Mermaid flowchart of one action: the happy path top to bottom, decisions for guards and case steps, each
|
|
6
|
+
# child action one linked box, and one exit node per declared failure or skip (AD-B20..AD-B24).
|
|
7
|
+
# @api private
|
|
8
|
+
class Flowchart
|
|
9
|
+
# @param action [Class] a named action
|
|
10
|
+
def initialize(action)
|
|
11
|
+
@action = action
|
|
12
|
+
@info = action.describe
|
|
13
|
+
@lines = ['flowchart TD', ' start([Start])']
|
|
14
|
+
@count = 0
|
|
15
|
+
end
|
|
16
|
+
|
|
17
|
+
# @return [String] the chart text, ending with a newline
|
|
18
|
+
def to_s
|
|
19
|
+
tails = Array(@info[:steps]).reduce([['start', nil]]) { |open, entry| step(entry, open) }
|
|
20
|
+
@lines << ' done([Done])'
|
|
21
|
+
connect(tails, 'done')
|
|
22
|
+
exits
|
|
23
|
+
"#{@lines.join("\n")}\n"
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
private
|
|
27
|
+
|
|
28
|
+
# Adds +entry+ after the +open+ ends; returns the ends the next step hangs off, as +[node, edge label]+ pairs.
|
|
29
|
+
def step(entry, open)
|
|
30
|
+
guard = entry[:guard] || {}
|
|
31
|
+
skipped = []
|
|
32
|
+
{ if: %w[yes no], unless: %w[no yes] }.each do |key, (run, skip)|
|
|
33
|
+
next unless guard.key?(key)
|
|
34
|
+
|
|
35
|
+
decision = add('g', "{\"#{escape(Words.guard_words(guard[key]))}?\"}")
|
|
36
|
+
connect(open, decision)
|
|
37
|
+
open = [[decision, run]]
|
|
38
|
+
skipped << [decision, skip]
|
|
39
|
+
end
|
|
40
|
+
body(entry, open) + skipped
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
def body(entry, open)
|
|
44
|
+
return case_body(entry, open) if entry[:type] == :case
|
|
45
|
+
|
|
46
|
+
node = box(entry)
|
|
47
|
+
connect(open, node)
|
|
48
|
+
[[node, nil]]
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
def box(entry)
|
|
52
|
+
child = entry[:name]
|
|
53
|
+
return add('s', "[\"#{escape(Words.plain_label(entry))}\"]") unless child.is_a?(Class)
|
|
54
|
+
|
|
55
|
+
node = add('s', "[[\"#{escape(entry[:description] || Words.title(child))}\"]]")
|
|
56
|
+
@lines << " click #{node} \"#{Words.link(@action, child)}\""
|
|
57
|
+
node
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
def case_body(entry, open)
|
|
61
|
+
decision = add('c', "{\"#{escape(Words.plain_label(entry))}?\"}")
|
|
62
|
+
connect(open, decision)
|
|
63
|
+
ends = Array(entry[:branches]).flat_map { |branch| step(branch[:step], [[decision, Words.on_words(branch[:on])]]) }
|
|
64
|
+
fallback = entry[:default]
|
|
65
|
+
ends + (fallback ? step(fallback, [[decision, 'anything else']]) : [[decision, 'anything else']])
|
|
66
|
+
end
|
|
67
|
+
|
|
68
|
+
def exits
|
|
69
|
+
{ failures: %w[f Stops], skips: ['k', 'Finishes early'] }.each do |key, (prefix, verb)|
|
|
70
|
+
@info[key].each_key do |code|
|
|
71
|
+
node = add(prefix, "[/\"#{verb}: #{escape(Words.humanize(code))}\"/]")
|
|
72
|
+
@lines << " start -->|any step| #{node}"
|
|
73
|
+
end
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
def add(prefix, shape)
|
|
78
|
+
@count += 1
|
|
79
|
+
node = "#{prefix}#{@count}"
|
|
80
|
+
@lines << " #{node}#{shape}"
|
|
81
|
+
node
|
|
82
|
+
end
|
|
83
|
+
|
|
84
|
+
def connect(open, target)
|
|
85
|
+
open.each do |from, label|
|
|
86
|
+
@lines << (label ? " #{from} -->|#{escape(label).tr('|', '/')}| #{target}" : " #{from} --> #{target}")
|
|
87
|
+
end
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
def escape(text)
|
|
91
|
+
text.to_s.tr('"', "'")
|
|
92
|
+
end
|
|
93
|
+
end
|
|
94
|
+
end
|
|
95
|
+
end
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Actionable
|
|
4
|
+
module Docs
|
|
5
|
+
# The Markdown page of one action, in the AD-B10 order.
|
|
6
|
+
# @api private
|
|
7
|
+
class Page
|
|
8
|
+
# The page's last line.
|
|
9
|
+
#
|
|
10
|
+
# @return [String]
|
|
11
|
+
FOOTER = "_Generated from the action's declarations by actionable-docs. Edit the action, not this page._"
|
|
12
|
+
# The hook lists in page order, with their lead-in words.
|
|
13
|
+
#
|
|
14
|
+
# @return [Hash{Symbol=>String}]
|
|
15
|
+
HOOKS = { on_success: 'When it succeeds', on_failure: 'When it stops', on_skip: 'When it finishes early',
|
|
16
|
+
after_commit: 'After the database commits', always: 'Every time, at the end' }.freeze
|
|
17
|
+
|
|
18
|
+
# @param action [Class] a named action
|
|
19
|
+
def initialize(action)
|
|
20
|
+
@action = action
|
|
21
|
+
@info = action.describe
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
# @return [String] the page, ending with one newline
|
|
25
|
+
def to_s
|
|
26
|
+
parts = ["# #{Words.title(@action)}"]
|
|
27
|
+
parts << @info[:description] if @info[:description]
|
|
28
|
+
parts << "```mermaid\n#{Flowchart.new(@action)}```"
|
|
29
|
+
parts << steps
|
|
30
|
+
parts.push(*[codes('It can stop because', @info[:failures]), codes('It can finish early because', @info[:skips]),
|
|
31
|
+
hooks, fields('What it needs', @info[:input]), fields('What it produces', @info[:output]),
|
|
32
|
+
calls].compact)
|
|
33
|
+
parts << FOOTER
|
|
34
|
+
"#{parts.join("\n\n")}\n"
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
private
|
|
38
|
+
|
|
39
|
+
def steps
|
|
40
|
+
entries = Array(@info[:steps])
|
|
41
|
+
return "## Steps\n\nIt has no steps." if entries.empty?
|
|
42
|
+
|
|
43
|
+
lines = entries.each_with_index.map { |entry, index| step_line(entry, index + 1) }
|
|
44
|
+
"## Steps\n\n#{lines.join("\n")}"
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
def step_line(entry, number)
|
|
48
|
+
return "#{number}. #{label(entry)}#{Words.guard_suffix(entry[:guard])}" unless entry[:type] == :case
|
|
49
|
+
|
|
50
|
+
head = "#{number}. Depending on #{Words.lower_first(Words.plain_label(entry))}#{Words.guard_suffix(entry[:guard])}:"
|
|
51
|
+
branches = Array(entry[:branches]).map { |branch| branch_line(Words.on_words(branch[:on]), branch[:step]) }
|
|
52
|
+
branches << branch_line('anything else', entry[:default]) if entry[:default]
|
|
53
|
+
[head, *branches].join("\n")
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
def branch_line(words, entry)
|
|
57
|
+
" - #{words}: #{label(entry)}#{Words.guard_suffix(entry[:guard])}"
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
# A step's words, with a child action as a link to its page.
|
|
61
|
+
def label(entry)
|
|
62
|
+
child = entry[:name]
|
|
63
|
+
return Words.plain_label(entry) unless child.is_a?(Class)
|
|
64
|
+
|
|
65
|
+
"[#{entry[:description] || Words.title(child)}](#{Words.link(@action, child)})"
|
|
66
|
+
end
|
|
67
|
+
|
|
68
|
+
def codes(heading, declarations)
|
|
69
|
+
return nil if declarations.empty?
|
|
70
|
+
|
|
71
|
+
lines = declarations.map do |code, declaration|
|
|
72
|
+
words = declaration[:description] || declaration[:message] || Words.humanize(code)
|
|
73
|
+
retry_note = { true => ' _(worth retrying)_', false => " _(don't retry)_" }[declaration[:metadata][:retry]]
|
|
74
|
+
"- **#{Words.humanize(code)}**: #{words}#{retry_note} `#{code}`"
|
|
75
|
+
end
|
|
76
|
+
"## #{heading}\n\n#{lines.join("\n")}"
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
def hooks
|
|
80
|
+
lines = HOOKS.filter_map do |kind, lead|
|
|
81
|
+
entries = @info[:hooks].fetch(kind, [])
|
|
82
|
+
next if entries.empty?
|
|
83
|
+
|
|
84
|
+
"- #{lead}: #{entries.map { |entry| "#{label(entry)}#{Words.guard_suffix(entry[:guard])}" }.join(', ')}"
|
|
85
|
+
end
|
|
86
|
+
lines.empty? ? nil : "## What happens after\n\n#{lines.join("\n")}"
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
def fields(heading, schema)
|
|
90
|
+
return nil if schema.nil? || schema.empty?
|
|
91
|
+
return "## #{heading}\n\nIt takes one of several input shapes." if schema.key?(:discriminated_on)
|
|
92
|
+
|
|
93
|
+
rows = schema.map do |name, field|
|
|
94
|
+
meaning = field[:description] ? field[:description].to_s.gsub('|', '\|') : '—'
|
|
95
|
+
"| #{Words.humanize(name)} | #{meaning} | #{field[:required] ? 'yes' : 'no'} |"
|
|
96
|
+
end
|
|
97
|
+
"## #{heading}\n\n| Field | Meaning | Required |\n|---|---|---|\n#{rows.join("\n")}"
|
|
98
|
+
end
|
|
99
|
+
|
|
100
|
+
def calls
|
|
101
|
+
children = Array(@info[:calls])
|
|
102
|
+
return nil if children.empty?
|
|
103
|
+
|
|
104
|
+
lines = children.map { |child| "- [#{Words.title(child)}](#{Words.link(@action, child)}) (found in source)" }
|
|
105
|
+
"## Also runs\n\n#{lines.join("\n")}"
|
|
106
|
+
end
|
|
107
|
+
end
|
|
108
|
+
end
|
|
109
|
+
end
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'rake'
|
|
4
|
+
require_relative '../docs'
|
|
5
|
+
|
|
6
|
+
module Actionable
|
|
7
|
+
module Docs
|
|
8
|
+
# Rake tasks for a host app: +actionable:docs+ writes the pages, +actionable:docs:check+ fails when the
|
|
9
|
+
# committed pages differ from fresh ones (AD-B32).
|
|
10
|
+
module Tasks
|
|
11
|
+
module_function
|
|
12
|
+
|
|
13
|
+
# Defines the two tasks.
|
|
14
|
+
#
|
|
15
|
+
# @param actions [Array<Class>, Proc] the actions to document, or a callable returning them (called when a task
|
|
16
|
+
# runs, so an app can load its code first)
|
|
17
|
+
# @param dir [String] the docs folder the pages live in
|
|
18
|
+
# @return [void]
|
|
19
|
+
def define(actions:, dir:)
|
|
20
|
+
list = -> { actions.respond_to?(:call) ? actions.call : actions }
|
|
21
|
+
Rake.application.last_description = "Write the action pages into #{dir}"
|
|
22
|
+
Rake::Task.define_task('actionable:docs') do
|
|
23
|
+
Docs.write(list.call, dir: dir).each { |path| puts "actionable-docs: wrote #{path}" }
|
|
24
|
+
end
|
|
25
|
+
Rake.application.last_description = "Fail when a page in #{dir} is missing or out of date"
|
|
26
|
+
Rake::Task.define_task('actionable:docs:check') { Tasks.check(list.call, dir) }
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
# @api private
|
|
30
|
+
# @param actions [Array<Class>]
|
|
31
|
+
# @param dir [String]
|
|
32
|
+
# @return [void]
|
|
33
|
+
def check(actions, dir)
|
|
34
|
+
stale = Docs.stale(actions, dir: dir)
|
|
35
|
+
unless stale.empty?
|
|
36
|
+
abort "actionable-docs: these pages are out of date; run rake actionable:docs and commit them:\n" \
|
|
37
|
+
"#{stale.join("\n")}"
|
|
38
|
+
end
|
|
39
|
+
puts "actionable-docs: #{actions.uniq.size} pages are current"
|
|
40
|
+
end
|
|
41
|
+
end
|
|
42
|
+
end
|
|
43
|
+
end
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'pathname'
|
|
4
|
+
|
|
5
|
+
module Actionable
|
|
6
|
+
module Docs
|
|
7
|
+
# The words a page and its chart use: titles, paths, labels, guard and branch words (AD-B2..AD-B4).
|
|
8
|
+
# @api private
|
|
9
|
+
module Words
|
|
10
|
+
# A guard label that is a method name, as opposed to a description.
|
|
11
|
+
#
|
|
12
|
+
# @return [Regexp]
|
|
13
|
+
METHOD_NAME = /\A[a-z_][A-Za-z0-9_]*[?!]?\z/
|
|
14
|
+
|
|
15
|
+
module_function
|
|
16
|
+
|
|
17
|
+
# @param klass [Class] a named action
|
|
18
|
+
# @return [String] its last name segment as words, only the first letter upper case
|
|
19
|
+
def title(klass)
|
|
20
|
+
sentence(split_words(klass.name.to_s.split('::').last.to_s, ' ').downcase)
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
# @param klass [Class] a named action
|
|
24
|
+
# @return [String] the page's relative path, e.g. +workshop/service_bike.md+
|
|
25
|
+
def path_for(klass)
|
|
26
|
+
"#{klass.name.to_s.split('::').map { |segment| split_words(segment, '_').downcase }.join('/')}.md"
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
# @param from [Class] the action whose page holds the link
|
|
30
|
+
# @param to [Class] the linked action
|
|
31
|
+
# @return [String] the relative path from +from+'s page to +to+'s
|
|
32
|
+
def link(from, to)
|
|
33
|
+
Pathname(path_for(to)).relative_path_from(Pathname(path_for(from)).dirname).to_s
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# @param name [Symbol, String] a method or code name
|
|
37
|
+
# @return [String] +fit_brakes+ as "Fit brakes" (a trailing +?+ or +!+ dropped)
|
|
38
|
+
def humanize(name)
|
|
39
|
+
sentence(name.to_s.sub(/[?!]\z/, '').tr('_', ' '))
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
# @param entry [Hash{Symbol=>Object}] a step entry from +describe+
|
|
43
|
+
# @return [String] its description, or its humanized name (the title for an action step)
|
|
44
|
+
def plain_label(entry)
|
|
45
|
+
return entry[:description] if entry[:description]
|
|
46
|
+
|
|
47
|
+
entry[:name].is_a?(Class) ? title(entry[:name]) : humanize(entry[:name])
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
# @param label [String] a +guard:+ label from +describe+
|
|
51
|
+
# @return [String] a method name as lower-case words; a description as it is
|
|
52
|
+
def guard_words(label)
|
|
53
|
+
METHOD_NAME.match?(label) ? label.sub(/[?!]\z/, '').tr('_', ' ') : label
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
# @param guard [Hash{Symbol=>String}, nil] an entry's +guard:+
|
|
57
|
+
# @return [String] +" (only when ...)"+, +" (skipped when ...)"+, both joined by +and+, or +""+
|
|
58
|
+
def guard_suffix(guard)
|
|
59
|
+
return '' unless guard
|
|
60
|
+
|
|
61
|
+
parts = []
|
|
62
|
+
parts << "only when #{guard_words(guard[:if])}" if guard.key?(:if)
|
|
63
|
+
parts << "skipped when #{guard_words(guard[:unless])}" if guard.key?(:unless)
|
|
64
|
+
" (#{parts.join(' and ')})"
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
# @param value [Object] a branch's +on+ value
|
|
68
|
+
# @return [String] an Array joined with +or+, a Regexp as +matching /src/+, anything else as text
|
|
69
|
+
def on_words(value)
|
|
70
|
+
case value
|
|
71
|
+
when Array then value.join(' or ')
|
|
72
|
+
when Regexp then "matching /#{value.source}/"
|
|
73
|
+
else value.to_s
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
# @param text [String]
|
|
78
|
+
# @return [String] with only its first letter changed to upper case
|
|
79
|
+
def sentence(text)
|
|
80
|
+
text.empty? ? text : text[0].to_s.upcase + text[1..].to_s
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
# @param text [String]
|
|
84
|
+
# @return [String] with only its first letter changed to lower case
|
|
85
|
+
def lower_first(text)
|
|
86
|
+
text.empty? ? text : text[0].to_s.downcase + text[1..].to_s
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
# @param segment [String] a constant name segment
|
|
90
|
+
# @param separator [String]
|
|
91
|
+
# @return [String] +ServiceBike+ split before each capital that follows a lower-case letter or digit
|
|
92
|
+
def split_words(segment, separator)
|
|
93
|
+
segment.gsub(/(?<=[a-z0-9])(?=[A-Z])/, separator)
|
|
94
|
+
end
|
|
95
|
+
end
|
|
96
|
+
end
|
|
97
|
+
end
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'fileutils'
|
|
4
|
+
require 'actionable'
|
|
5
|
+
require_relative 'docs/version'
|
|
6
|
+
require_relative 'docs/words'
|
|
7
|
+
require_relative 'docs/flowchart'
|
|
8
|
+
require_relative 'docs/page'
|
|
9
|
+
|
|
10
|
+
# The actionable-rb namespace; this gem adds {Docs}.
|
|
11
|
+
module Actionable
|
|
12
|
+
# Process pages for actions: Markdown with a Mermaid flowchart, built from +describe+ and the descriptions, for
|
|
13
|
+
# people who read about an action rather than its code. Nothing here runs an action.
|
|
14
|
+
module Docs
|
|
15
|
+
module_function
|
|
16
|
+
|
|
17
|
+
# The page for one action.
|
|
18
|
+
#
|
|
19
|
+
# @param action [Class] a named Actionable::Action subclass
|
|
20
|
+
# @return [String] Markdown, ending with one newline
|
|
21
|
+
# @raise [ArgumentError] for anything else
|
|
22
|
+
def markdown(action)
|
|
23
|
+
Page.new(checked(action)).to_s
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
# @param action [Class] a named Actionable::Action subclass
|
|
27
|
+
# @return [String] the words of its title, e.g. "Service bike"
|
|
28
|
+
# @raise [ArgumentError] for anything else
|
|
29
|
+
def title(action)
|
|
30
|
+
Words.title(checked(action))
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# @param action [Class] a named Actionable::Action subclass
|
|
34
|
+
# @return [String] the page's path relative to the docs folder, e.g. +workshop/service_bike.md+
|
|
35
|
+
# @raise [ArgumentError] for anything else
|
|
36
|
+
def path_for(action)
|
|
37
|
+
Words.path_for(checked(action))
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# Writes every action's page under +dir+, creating folders.
|
|
41
|
+
#
|
|
42
|
+
# @param actions [Array<Class>] named action classes; a repeat is written once
|
|
43
|
+
# @param dir [String] the docs folder
|
|
44
|
+
# @return [Array<String>] the paths written, in the given order
|
|
45
|
+
def write(actions, dir:)
|
|
46
|
+
actions.uniq.map do |action|
|
|
47
|
+
path = File.join(dir, path_for(action))
|
|
48
|
+
FileUtils.mkdir_p(File.dirname(path))
|
|
49
|
+
File.write(path, markdown(action))
|
|
50
|
+
path
|
|
51
|
+
end
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
# The pages under +dir+ that are missing or differ from a fresh one. Writes nothing.
|
|
55
|
+
#
|
|
56
|
+
# @param actions [Array<Class>] named action classes
|
|
57
|
+
# @param dir [String] the docs folder
|
|
58
|
+
# @return [Array<String>] the stale paths, empty when every page is current
|
|
59
|
+
def stale(actions, dir:)
|
|
60
|
+
actions.uniq.filter_map do |action|
|
|
61
|
+
path = File.join(dir, path_for(action))
|
|
62
|
+
path unless File.file?(path) && File.read(path) == markdown(action)
|
|
63
|
+
end
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
# @api private
|
|
67
|
+
# @param action [Object]
|
|
68
|
+
# @return [Class] the action, when it is a named Actionable::Action subclass
|
|
69
|
+
# @raise [ArgumentError] for anything else
|
|
70
|
+
def checked(action)
|
|
71
|
+
return action if action.is_a?(Class) && action < Actionable::Action && action.name
|
|
72
|
+
|
|
73
|
+
raise ArgumentError, "Actionable::Docs needs a named Actionable::Action subclass, got #{action.inspect}"
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
end
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# The actionable-rb namespace; this gem adds {Docs}.
|
|
2
|
+
module Actionable
|
|
3
|
+
# Process pages for actions: Markdown with a Mermaid flowchart, built from +describe+ and the descriptions, for
|
|
4
|
+
# people who read about an action rather than its code. Nothing here runs an action.
|
|
5
|
+
module Docs
|
|
6
|
+
VERSION: String
|
|
7
|
+
|
|
8
|
+
# The page for one action.
|
|
9
|
+
#
|
|
10
|
+
# _@param_ `action` — a named Actionable::Action subclass
|
|
11
|
+
#
|
|
12
|
+
# _@return_ — Markdown, ending with one newline
|
|
13
|
+
def self.markdown: (Class action) -> String
|
|
14
|
+
|
|
15
|
+
# _@param_ `action` — a named Actionable::Action subclass
|
|
16
|
+
#
|
|
17
|
+
# _@return_ — the words of its title, e.g. "Service bike"
|
|
18
|
+
def self.title: (Class action) -> String
|
|
19
|
+
|
|
20
|
+
# _@param_ `action` — a named Actionable::Action subclass
|
|
21
|
+
#
|
|
22
|
+
# _@return_ — the page's path relative to the docs folder, e.g. +workshop/service_bike.md+
|
|
23
|
+
def self.path_for: (Class action) -> String
|
|
24
|
+
|
|
25
|
+
# Writes every action's page under +dir+, creating folders.
|
|
26
|
+
#
|
|
27
|
+
# _@param_ `actions` — named action classes; a repeat is written once
|
|
28
|
+
#
|
|
29
|
+
# _@param_ `dir` — the docs folder
|
|
30
|
+
#
|
|
31
|
+
# _@return_ — the paths written, in the given order
|
|
32
|
+
def self.write: (::Array[Class] actions, dir: String) -> ::Array[String]
|
|
33
|
+
|
|
34
|
+
# The pages under +dir+ that are missing or differ from a fresh one. Writes nothing.
|
|
35
|
+
#
|
|
36
|
+
# _@param_ `actions` — named action classes
|
|
37
|
+
#
|
|
38
|
+
# _@param_ `dir` — the docs folder
|
|
39
|
+
#
|
|
40
|
+
# _@return_ — the stale paths, empty when every page is current
|
|
41
|
+
def self.stale: (::Array[Class] actions, dir: String) -> ::Array[String]
|
|
42
|
+
|
|
43
|
+
# _@param_ `action`
|
|
44
|
+
#
|
|
45
|
+
# _@return_ — the action, when it is a named Actionable::Action subclass
|
|
46
|
+
def self.checked: (Object action) -> Class
|
|
47
|
+
|
|
48
|
+
# The Markdown page of one action, in the AD-B10 order.
|
|
49
|
+
# @api private
|
|
50
|
+
class Page
|
|
51
|
+
FOOTER: String
|
|
52
|
+
HOOKS: ::Hash[Symbol, String]
|
|
53
|
+
|
|
54
|
+
# _@param_ `action` — a named action
|
|
55
|
+
def initialize: (Class action) -> void
|
|
56
|
+
|
|
57
|
+
# _@return_ — the page, ending with one newline
|
|
58
|
+
def to_s: () -> String
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
# Rake tasks for a host app: +actionable:docs+ writes the pages, +actionable:docs:check+ fails when the
|
|
62
|
+
# committed pages differ from fresh ones (AD-B32).
|
|
63
|
+
module Tasks
|
|
64
|
+
# Defines the two tasks.
|
|
65
|
+
#
|
|
66
|
+
# _@param_ `actions` — the actions to document, or a callable returning them (called when a task runs, so an app can load its code first)
|
|
67
|
+
#
|
|
68
|
+
# _@param_ `dir` — the docs folder the pages live in
|
|
69
|
+
def self.define: (actions: (::Array[Class] | Proc), dir: String) -> void
|
|
70
|
+
|
|
71
|
+
# _@param_ `actions`
|
|
72
|
+
#
|
|
73
|
+
# _@param_ `dir`
|
|
74
|
+
def self.check: (::Array[Class] actions, String dir) -> void
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
# The words a page and its chart use: titles, paths, labels, guard and branch words (AD-B2..AD-B4).
|
|
78
|
+
# @api private
|
|
79
|
+
module Words
|
|
80
|
+
METHOD_NAME: Regexp
|
|
81
|
+
|
|
82
|
+
# _@param_ `klass` — a named action
|
|
83
|
+
#
|
|
84
|
+
# _@return_ — its last name segment as words, only the first letter upper case
|
|
85
|
+
def self.title: (Class klass) -> String
|
|
86
|
+
|
|
87
|
+
# _@param_ `klass` — a named action
|
|
88
|
+
#
|
|
89
|
+
# _@return_ — the page's relative path, e.g. +workshop/service_bike.md+
|
|
90
|
+
def self.path_for: (Class klass) -> String
|
|
91
|
+
|
|
92
|
+
# _@param_ `from` — the action whose page holds the link
|
|
93
|
+
#
|
|
94
|
+
# _@param_ `to` — the linked action
|
|
95
|
+
#
|
|
96
|
+
# _@return_ — the relative path from +from+'s page to +to+'s
|
|
97
|
+
def self.link: (Class from, Class to) -> String
|
|
98
|
+
|
|
99
|
+
# _@param_ `name` — a method or code name
|
|
100
|
+
#
|
|
101
|
+
# _@return_ — +fit_brakes+ as "Fit brakes" (a trailing +?+ or +!+ dropped)
|
|
102
|
+
def self.humanize: ((Symbol | String) name) -> String
|
|
103
|
+
|
|
104
|
+
# _@param_ `entry` — a step entry from +describe+
|
|
105
|
+
#
|
|
106
|
+
# _@return_ — its description, or its humanized name (the title for an action step)
|
|
107
|
+
def self.plain_label: (::Hash[Symbol, Object] entry) -> String
|
|
108
|
+
|
|
109
|
+
# _@param_ `label` — a +guard:+ label from +describe+
|
|
110
|
+
#
|
|
111
|
+
# _@return_ — a method name as lower-case words; a description as it is
|
|
112
|
+
def self.guard_words: (String label) -> String
|
|
113
|
+
|
|
114
|
+
# _@param_ `guard` — an entry's +guard:+
|
|
115
|
+
#
|
|
116
|
+
# _@return_ — +" (only when ...)"+, +" (skipped when ...)"+, both joined by +and+, or +""+
|
|
117
|
+
def self.guard_suffix: (::Hash[Symbol, String]? guard) -> String
|
|
118
|
+
|
|
119
|
+
# _@param_ `value` — a branch's +on+ value
|
|
120
|
+
#
|
|
121
|
+
# _@return_ — an Array joined with +or+, a Regexp as +matching /src/+, anything else as text
|
|
122
|
+
def self.on_words: (Object value) -> String
|
|
123
|
+
|
|
124
|
+
# _@param_ `text`
|
|
125
|
+
#
|
|
126
|
+
# _@return_ — with only its first letter changed to upper case
|
|
127
|
+
def self.sentence: (String text) -> String
|
|
128
|
+
|
|
129
|
+
# _@param_ `text`
|
|
130
|
+
#
|
|
131
|
+
# _@return_ — with only its first letter changed to lower case
|
|
132
|
+
def self.lower_first: (String text) -> String
|
|
133
|
+
|
|
134
|
+
# _@param_ `segment` — a constant name segment
|
|
135
|
+
#
|
|
136
|
+
# _@param_ `separator`
|
|
137
|
+
#
|
|
138
|
+
# _@return_ — +ServiceBike+ split before each capital that follows a lower-case letter or digit
|
|
139
|
+
def self.split_words: (String segment, String separator) -> String
|
|
140
|
+
end
|
|
141
|
+
|
|
142
|
+
# The Mermaid flowchart of one action: the happy path top to bottom, decisions for guards and case steps, each
|
|
143
|
+
# child action one linked box, and one exit node per declared failure or skip (AD-B20..AD-B24).
|
|
144
|
+
# @api private
|
|
145
|
+
class Flowchart
|
|
146
|
+
# _@param_ `action` — a named action
|
|
147
|
+
def initialize: (Class action) -> void
|
|
148
|
+
|
|
149
|
+
# _@return_ — the chart text, ending with a newline
|
|
150
|
+
def to_s: () -> String
|
|
151
|
+
end
|
|
152
|
+
end
|
|
153
|
+
end
|
metadata
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: actionable-docs
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 1.0.0.pre1
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Adrian Madrid
|
|
8
|
+
bindir: bin
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies:
|
|
12
|
+
- !ruby/object:Gem::Dependency
|
|
13
|
+
name: actionable-rb
|
|
14
|
+
requirement: !ruby/object:Gem::Requirement
|
|
15
|
+
requirements:
|
|
16
|
+
- - ">="
|
|
17
|
+
- !ruby/object:Gem::Version
|
|
18
|
+
version: 2.0.0.pre1
|
|
19
|
+
- - "<"
|
|
20
|
+
- !ruby/object:Gem::Version
|
|
21
|
+
version: '3'
|
|
22
|
+
type: :runtime
|
|
23
|
+
prerelease: false
|
|
24
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
25
|
+
requirements:
|
|
26
|
+
- - ">="
|
|
27
|
+
- !ruby/object:Gem::Version
|
|
28
|
+
version: 2.0.0.pre1
|
|
29
|
+
- - "<"
|
|
30
|
+
- !ruby/object:Gem::Version
|
|
31
|
+
version: '3'
|
|
32
|
+
description: Renders each action as a page (steps, why it can stop, what happens after,
|
|
33
|
+
what it needs and produces) from its declarations, with rake tasks that write the
|
|
34
|
+
pages and fail when they drift.
|
|
35
|
+
email:
|
|
36
|
+
- adrian.madrid@timeworxs.com
|
|
37
|
+
executables: []
|
|
38
|
+
extensions: []
|
|
39
|
+
extra_rdoc_files: []
|
|
40
|
+
files:
|
|
41
|
+
- CHANGELOG.md
|
|
42
|
+
- LICENSE.txt
|
|
43
|
+
- README.md
|
|
44
|
+
- lib/actionable/docs.rb
|
|
45
|
+
- lib/actionable/docs/flowchart.rb
|
|
46
|
+
- lib/actionable/docs/page.rb
|
|
47
|
+
- lib/actionable/docs/tasks.rb
|
|
48
|
+
- lib/actionable/docs/version.rb
|
|
49
|
+
- lib/actionable/docs/words.rb
|
|
50
|
+
- sig/actionable-docs.rbs
|
|
51
|
+
homepage: https://github.com/gliders-rb/gems
|
|
52
|
+
licenses:
|
|
53
|
+
- MIT
|
|
54
|
+
metadata:
|
|
55
|
+
source_code_uri: https://github.com/gliders-rb/gems/tree/main/adapters/actionable-docs
|
|
56
|
+
changelog_uri: https://github.com/gliders-rb/gems/blob/main/adapters/actionable-docs/CHANGELOG.md
|
|
57
|
+
rubygems_mfa_required: 'true'
|
|
58
|
+
rdoc_options: []
|
|
59
|
+
require_paths:
|
|
60
|
+
- lib
|
|
61
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
62
|
+
requirements:
|
|
63
|
+
- - ">="
|
|
64
|
+
- !ruby/object:Gem::Version
|
|
65
|
+
version: '3.3'
|
|
66
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
67
|
+
requirements:
|
|
68
|
+
- - ">="
|
|
69
|
+
- !ruby/object:Gem::Version
|
|
70
|
+
version: '0'
|
|
71
|
+
requirements: []
|
|
72
|
+
rubygems_version: 3.6.9
|
|
73
|
+
specification_version: 4
|
|
74
|
+
summary: 'Process pages for actionable-rb actions: Markdown and a Mermaid flowchart
|
|
75
|
+
a product manager can read.'
|
|
76
|
+
test_files: []
|