auto-platform-guide 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ccccab1be99709c35e9851337b7f95f722124a4f23368de67c76c7e6539f6c5
+  data.tar.gz: cebdb9082d0502cd57550a0c567809bfee9beeb606faf7800b898dfa049da294
+SHA512:
+  metadata.gz: 797fdaf7358ada5c81bf394f57f38490e2734c1bb9d269676d3d0c51e9b0513f7f9d1db9386a409c453f41f80f2951ddae076936e092967b58fd8db702e350fd
+  data.tar.gz: 6f6b428ebf18973783dc42b5ca427a41a8ab0b91bdffd9fad9ed972f8e617e13b7d784f5c499da9d2eacdc6dcdc8aaee0d380d672570aad39d0ec74a95c6e899

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-26
+
+Initial release: spec-driven doc generator, `doc_screenshot` helper, configurable
+browser driver wiring, and markdown docs viewer.
+
+### Added
+
+- Rake tasks for generating, checking, re-rendering and rebuilding the TOC,
+  shipped with the gem.
+- `readme_preamble` configuration for the markdown above the generated README
+  table of contents.
+- The gem's own guide in `docs/platform-guide/`, generated from `spec/docs/` and
+  verified in CI.
+
+### Changed
+
+- Viewer links, breadcrumbs and wikilinks follow the `docs_path` configuration
+  instead of hardcoding `/docs`.
+- The docs viewer template no longer depends on host helpers, partials or
+  assets (`content_header`, `shared/_box`, a host `docs_path` helper, `docs.js`).
+
+### Fixed
+
+- Doc comments preserve indentation beyond the `# ` prefix, so fenced code
+  blocks keep their layout.
+- Adjacent callout blockquotes render as separate callouts instead of one merged
+  quote.
+
+### Removed
+
+- `bin/generate-docs`; use `auto_platform_guide:generate` instead.
+
+[Unreleased]: https://github.com/mauriciozaffari/auto-platform-guide/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mauriciozaffari/auto-platform-guide/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauricio Zaffari
+
+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,161 @@
+# Auto Platform Guide
+
+Generate in-app documentation from system specs.
+
+The gem documents itself: `docs/platform-guide/` is generated from
+`spec/docs/` by `rake auto_platform_guide:render` and checked in CI.
+
+- `AutoPlatformGuide::Generator` renders markdown guides from `# =` doc comments in
+  system specs into `generated_docs_dir`, with an ordered README TOC grouped by
+  `@category`/`@order` directives.
+- `AutoPlatformGuide.setup_rspec(config)` wires system-spec screenshot support:
+  `doc_screenshot('name')` captures to `screenshots_dir` when `SCREENSHOTS=true`,
+  and specs run on `rack_test` unless they need a browser (`:js` tag or
+  `SCREENSHOTS=true`). Browser driver is `:playwright` by default; set
+  `config.browser_driver = :selenium` to use Selenium.
+- The markdown viewer: `Document` + the `docs/show` template, rendered through
+  `AutoPlatformGuide::DocsControllerActions`. Include it in the host app's docs
+  controller so authentication stays application-owned:
+
+  ```ruby
+  class DocsController < AdminController
+    include AutoPlatformGuide::DocsControllerActions
+  end
+  ```
+
+  ```ruby
+  # config/routes.rb
+  get '/docs(/*id)', to: 'docs#show', as: 'docs'
+  ```
+
+  The shipped `docs/show` template uses plain markup and inline JavaScript; it
+  needs no host helpers, partials or assets. Links are built from `docs_path`, so
+  set it to the path you mount (default `/docs`). Mermaid fenced blocks render
+  when a global `mermaid` is present and stay readable as source otherwise.
+  Override the template in the host app to change the surrounding chrome.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'auto-platform-guide'
+```
+
+Tagged releases publish to RubyGems automatically.
+
+## Setup
+
+```ruby
+# config/initializers/auto_platform_guide.rb
+AutoPlatformGuide.configure do |config|
+  config.docs_root = 'docs'
+  config.docs_path = '/docs'
+  config.generated_docs_dir = 'docs/platform-guide'
+  config.screenshots_dir = 'docs/screenshots'
+  config.specs_glob = 'spec/system/**/*_spec.rb'
+  config.browser_driver = :playwright # or :selenium
+  config.readme_preamble = nil
+end
+```
+
+Every key is optional; the values above are the defaults. Keep
+`generated_docs_dir` inside `docs_root`, since the viewer only reads from
+`docs_root`.
+
+The `:playwright` default needs `capybara-playwright-driver` in the host app;
+`:selenium` needs `selenium-webdriver`. `capybara` itself is a gem dependency.
+`readme_preamble` is markdown placed above the generated README's table of
+contents; `nil` keeps `AutoPlatformGuide::Generator::README_PREAMBLE`. Note:
+`:selenium` support is unit-tested with mocked drivers — no CI job boots a real
+browser under either driver.
+
+```ruby
+# spec/rails_helper.rb
+require 'auto_platform_guide/rspec'
+
+RSpec.configure do |config|
+  AutoPlatformGuide.setup_rspec(config)
+end
+```
+
+## Writing a documented spec
+
+Doc comments are parsed from the files matched by `specs_glob`. A spec file is
+picked up when it has a `# = Heading` at column 0.
+
+```ruby
+# spec/system/orders_spec.rb
+require 'rails_helper'
+
+# @category Orders
+# @order 200
+#
+# = Orders
+# Create and track customer orders.
+#
+# == Creating an order
+# Pick a customer, add line items and save.
+
+RSpec.describe 'Orders', type: :system do
+  it 'creates an order' do
+    visit new_admin_order_path
+
+    fill_in 'Reference', with: 'ORD-1'
+    click_button 'Save'
+    expect(page).to have_content('Order created')
+
+    doc_screenshot('orders/created')
+  end
+end
+```
+
+- `# = Heading` renders as `<h1>`; every extra `=` adds a level (`# ==` → `<h2>`).
+- Comment lines after a heading are its body, up to the next heading or the first
+  non-comment line. Sections can also sit directly above the examples they describe.
+- `@category` and `@order` only place the guide in the README TOC; they are
+  stripped from the body. Specs without them fall under `Other` / `999_999`.
+- The generator parses comments and embeds only screenshots whose PNG already
+  exists on disk. `generate` runs the spec first to capture them; `render` and
+  `check` never run specs.
+
+`doc_screenshot('orders/created')` writes `docs/screenshots/orders/created.png`
+when screenshots are enabled, and does nothing otherwise.
+
+## Capturing screenshots
+
+```bash
+SCREENSHOTS=true bundle exec rspec spec/system/orders_spec.rb
+rake auto_platform_guide:generate
+```
+
+`SCREENSHOTS=true` drives every system example in that run through the configured
+browser (`:playwright` by default) and saves each `doc_screenshot` call. Without
+it, system specs use `rack_test`; tag individual examples `:js` when only they
+need a browser.
+
+The helper is included for `type: :system` only, so keep that metadata. A
+screenshot is rendered after the heading block that precedes its call.
+
+## Rake tasks
+
+Generating docs is a rake task shipped with the gem. Rails apps load it through
+the engine; anywhere else, require it from your `Rakefile`:
+
+```ruby
+require 'auto_platform_guide/rake_tasks'
+```
+
+```bash
+rake auto_platform_guide:generate                      # all documented specs
+rake "auto_platform_guide:generate[spec/foo_spec.rb]"  # one spec
+rake auto_platform_guide:check                         # verify docs; non-zero when stale
+rake auto_platform_guide:readme                        # rebuild the README TOC
+rake auto_platform_guide:render                        # re-render, reuse screenshots on disk
+```
+
+## Tests
+
+```bash
+bin/setup
+bundle exec rspec
+```

data/app/views/docs/show.html.erb

@@ -0,0 +1,46 @@
+<% content_for :title, @document.title %>
+
+<section class="content-header">
+  <h1><%= @document.title %></h1>
+
+  <ol class="breadcrumb">
+    <li><%= link_to 'Documentation', AutoPlatformGuide::Document.docs_path %></li>
+    <% @document.breadcrumbs.each do |crumb| %>
+      <li><%= link_to crumb[:name], crumb[:path] %></li>
+    <% end %>
+  </ol>
+</section>
+
+<section class="content documentation">
+  <div class="box">
+    <div class="box-body">
+      <%= @document.render %>
+    </div>
+  </div>
+</section>
+
+<%# Mermaid diagrams are an enhancement: without a global `mermaid`, the
+    renderer's <pre class="mermaid"> blocks stay visible as source. %>
+<%= javascript_tag nonce: true do %>
+  (() => {
+    if (window.autoPlatformGuideDocsReady) return
+    window.autoPlatformGuideDocsReady = true
+
+    const renderDiagrams = () => {
+      if (!window.mermaid) return
+
+      const nodes = document.querySelectorAll('pre.mermaid:not([data-processed="true"])')
+      if (!nodes.length) return
+
+      window.mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: 'strict',
+        theme: window.darkMode ? 'dark' : 'default'
+      })
+      window.mermaid.run({ nodes })
+    }
+
+    document.addEventListener('turbo:load', renderDiagrams)
+    if (document.readyState === 'complete') renderDiagrams()
+  })()
+<% end %>

data/lib/auto-platform-guide.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'auto_platform_guide'

data/lib/auto_platform_guide/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module AutoPlatformGuide
+  class Configuration
+    # Where the viewer looks for markdown. The generator writes under
+    # generated_docs_dir, which lives inside this directory.
+    attr_accessor :docs_root
+    # Where DocGenerator writes the generated guides (specs -> markdown).
+    attr_accessor :generated_docs_dir
+    # Where doc_screenshot writes PNGs.
+    attr_accessor :screenshots_dir
+    # Glob (relative to repo root) for specs searched for doc comments.
+    attr_accessor :specs_glob
+    # Browser driver used when a system spec needs a real browser:
+    # :playwright (default) or :selenium.
+    attr_accessor :browser_driver
+    # Markdown written above the generated README table of contents. Defaults to
+    # Generator::README_PREAMBLE when nil.
+    attr_accessor :readme_preamble
+    # URL prefix where the docs viewer is mounted. Links, breadcrumbs and
+    # wikilinks are built from it, so it must match the host's route.
+    attr_reader :docs_path
+
+    def initialize
+      @docs_root = 'docs'
+      @generated_docs_dir = 'docs/platform-guide'
+      @screenshots_dir = 'docs/screenshots'
+      @specs_glob = 'spec/system/**/*_spec.rb'
+      @browser_driver = :playwright
+      @readme_preamble = nil
+      @docs_path = '/docs'
+    end
+
+    def docs_path=(path)
+      @docs_path = path.chomp('/')
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+end

data/lib/auto_platform_guide/docs_controller_actions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module AutoPlatformGuide
+  # Include into the host app's docs controller. The host keeps its own
+  # controller class so authentication (before_actions, layouts) stays
+  # application-owned:
+  #
+  #   class DocsController < AdminController
+  #     include AutoPlatformGuide::DocsControllerActions
+  #   end
+  module DocsControllerActions
+    def show
+      @document = Document.find(params[:id] || 'README')
+      # Markdown links end in `.md`, which Rails would otherwise read as the response format.
+      render template: 'docs/show', formats: :html
+    end
+  end
+end

data/lib/auto_platform_guide/document.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'pathname'
+require 'redcarpet'
+require 'rouge'
+require 'active_model'
+require 'action_view'
+require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/string/inflections'
+
+module AutoPlatformGuide
+  # A markdown document under the configured docs root, rendered for /docs.
+  class Document
+    include ActiveModel::Model
+
+    class RecordNotFound < StandardError; end
+
+    FOLDER_INDEX_NAMES = ['README', '00 - Index'].freeze
+
+    class Renderer < Redcarpet::Render::HTML
+      include ActionView::Helpers::TagHelper
+      include ActionView::Helpers::SanitizeHelper
+
+      # Obsidian wikilink: [[Note]], [[Note#Heading]], [[Note|Alias]] (and combinations).
+      WIKILINK = /\[\[([^\]#|]+)(?:#([^\]|]+))?(?:\|([^\]]+))?\]\]/
+      CALLOUT = /\A<p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\](?:<br>\s*)?/i
+      CALLOUT_ICONS = {
+        'note' => 'info-circle',
+        'tip' => 'lightbulb-o',
+        'important' => 'exclamation-circle',
+        'warning' => 'warning',
+        'caution' => 'ban'
+      }.freeze
+
+      # Redcarpet merges adjacent blockquotes into one callback, so split the
+      # quote at each callout marker and render them separately.
+      CALLOUT_SPLIT = /(?=<p>\[!(?:NOTE|TIP|IMPORTANT|WARNING|CAUTION)\])/i
+
+      def self.render(path, base_dir: nil)
+        new(base_dir:).render(path)
+      end
+
+      def initialize(base_dir: nil, docs_path: nil, **options)
+        @base_dir = base_dir
+        @docs_path = (docs_path || Document.docs_path).chomp('/')
+        super(options.merge(with_toc_data: true, hard_wrap: true))
+      end
+
+      def sanitize(html)
+        tags = ActionView::Base.sanitized_allowed_tags + %w[table thead tbody th tr td img i]
+        attributes = ActionView::Base.sanitized_allowed_attributes + %w[style colspan src alt id class aria-hidden]
+        super(html, tags:, attributes:)
+      end
+
+      def markdown
+        @markdown ||= Redcarpet::Markdown.new(
+          self,
+          fenced_code_blocks: true,
+          tables: true,
+          autolink: true,
+          strikethrough: true
+        )
+      end
+
+      def render(path)
+        sanitize(markdown.render(File.read(path)))
+      end
+
+      # Convert Obsidian wikilinks to markdown links before parsing, leaving any
+      # text inside fenced or inline code untouched.
+      def preprocess(document)
+        replace_wikilinks(document)
+      end
+
+      def block_code(code, language)
+        # Mermaid diagrams are rendered client-side: emit the raw source in a
+        # <pre class="mermaid"> for mermaid.js, never syntax-highlighted.
+        return content_tag(:pre, code, class: 'mermaid') if language == 'mermaid'
+
+        lexer = Rouge::Lexer.find_fancy(language.to_s, code) || Rouge::Lexers::PlainText.new
+        formatter = Rouge::Formatters::HTMLInline.new(Rouge::Themes::Github.mode(:dark).new)
+        code = formatter.format(lexer.lex(code))
+        content_tag(:pre, class: 'code-block') do
+          content_tag(:code, sanitize(code), class: "language-#{lexer.tag}")
+        end
+      end
+
+      def image(link, title, alt_text)
+        # tag.img renders HTML5 without the self-closing slash the specs assert.
+        tag(:img, src: link, alt: alt_text, title:, class: 'img-responsive') # rubocop:disable Rails/ContentTag
+      end
+
+      def block_quote(quote)
+        quote.split(CALLOUT_SPLIT).reject(&:empty?).map { |segment| render_quote(segment) }.join("\n")
+      end
+
+      private
+
+      def render_quote(segment)
+        callout = segment.match(CALLOUT)
+        return %(<blockquote>#{segment}</blockquote>) unless callout
+
+        type = callout[1].downcase
+        body = segment.sub(CALLOUT, '<p>')
+        icon = tag.i(class: "fa fa-#{CALLOUT_ICONS.fetch(type)}", aria: { hidden: true })
+        title = %(<p class="callout-title">#{icon} #{type.titleize}</p>)
+
+        %(<blockquote class="callout callout-#{type}">#{title}\n#{body}</blockquote>)
+      end
+
+      def replace_wikilinks(document)
+        in_fence = false
+
+        document.each_line.map do |line|
+          if line.start_with?('```')
+            in_fence = !in_fence
+            line
+          elsif in_fence
+            line
+          else
+            replace_wikilinks_in_line(line)
+          end
+        end.join
+      end
+
+      def replace_wikilinks_in_line(line)
+        line.split(/(`[^`]*`)/).map do |part|
+          if part.start_with?('`')
+            part
+          else
+            part.gsub(WIKILINK) do
+              wikilink_markdown(::Regexp.last_match(1), ::Regexp.last_match(2), ::Regexp.last_match(3))
+            end
+          end
+        end.join
+      end
+
+      def wikilink_markdown(name, heading, alias_text)
+        name = name.strip
+        label = alias_text&.strip
+        label ||= heading ? "#{name} › #{heading.strip}" : name
+        "[#{escape_markdown(label)}](#{wikilink_url(name, heading)})"
+      end
+
+      # Escape characters the link label would otherwise trigger as markdown
+      # (emphasis, links, code) so snake_case names render literally.
+      def escape_markdown(text)
+        text.gsub(/[\\_*\[\]`]/) { |char| "\\#{char}" }
+      end
+
+      def wikilink_url(name, heading)
+        segments = [@base_dir, name].compact_blank
+        url = "#{@docs_path}/#{segments.map { |segment| ERB::Util.url_encode(segment) }.join('/')}"
+        url += "##{heading_anchor(heading)}" if heading
+        url
+      end
+
+      # Mirror Redcarpet's with_toc_data anchor generation for [[Note#Heading]]:
+      # drop non-alphanumerics (underscores included), then collapse whitespace to "-".
+      def heading_anchor(heading)
+        heading.strip.downcase.gsub(/[^a-z0-9\s]/, '').gsub(/\s+/, '-').gsub(/^-|-$/, '')
+      end
+    end
+
+    attr_reader :id, :name, :path
+
+    class << self
+      def where(folder: nil, name: nil)
+        prefix = folder ? "#{docs_root}/#{folder}/" : "{#{docs_root}/**/,}"
+        Rails.root.glob("#{prefix}#{name || '*'}.md").sort.map { |path| new(path) }
+      end
+
+      alias all where
+      delegate :first, :last, to: :where
+
+      def find(name)
+        # .lazy stops at the first index file that exists.
+        where(name:).first ||
+          FOLDER_INDEX_NAMES.lazy.filter_map { |index| where(folder: name, name: index).first }.first ||
+          raise(RecordNotFound, "Couldn't find document #{name}")
+      end
+
+      def docs_root
+        AutoPlatformGuide.configuration.docs_root
+      end
+
+      def docs_path
+        AutoPlatformGuide.configuration.docs_path
+      end
+    end
+
+    def initialize(path)
+      @path = path
+      relative_path = Pathname(path).relative_path_from(Rails.root).to_s
+      prefix = Regexp.escape(AutoPlatformGuide.configuration.docs_root)
+      @id = relative_path.match(%r{\A(?:#{prefix}/)?(?<id>.*)\.md\z})&.[](:id)
+      @name = File.basename(path, '.md')
+    end
+
+    def render
+      dir = File.dirname(id)
+      Renderer.render(path, base_dir: dir == '.' ? nil : dir)
+    end
+
+    def title
+      name.titleize
+    end
+
+    def breadcrumbs
+      parts = id.split('/')
+
+      parts.each_with_index.map do |part, i|
+        { name: part.titleize, path: "#{self.class.docs_path}/#{parts[0..i].join('/')}" }
+      end
+    end
+  end
+end

data/lib/auto_platform_guide/engine.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'rails/engine'
+
+module AutoPlatformGuide
+  class Engine < ::Rails::Engine
+    initializer 'auto_platform_guide.view_paths', before: :add_view_paths do |app|
+      app.config.paths['app/views'].push(root.join('app', 'views'))
+    end
+
+    rake_tasks do
+      require 'auto_platform_guide/rake_tasks'
+    end
+  end
+end

data/lib/auto_platform_guide/generator.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+
+module AutoPlatformGuide
+  # Generates markdown guides from system specs with doc comments, plus the
+  # README table of contents. Doc comments are `# = Heading` blocks in spec
+  # files; `doc_screenshot('name')` calls reference PNGs captured during a
+  # SCREENSHOTS=true run.
+  class Generator
+    # Fallbacks for specs that omit the directives below. Specs with no
+    # `@category` collect under DEFAULT_CATEGORY; specs with no `@order` sort
+    # after numbered ones. Both defaults push such docs to the end of the TOC.
+    DEFAULT_CATEGORY = 'Other'
+    DEFAULT_ORDER = 999_999
+
+    FLAGS = %w[--check --readme-only --render-only].freeze
+
+    README_PREAMBLE = <<~MARKDOWN
+      <h1 id="platform-guide">Platform Guide</h1>
+
+      This guide is the primary, automatically generated reference for this
+      application. It is extracted from documented specs, so every page reflects
+      behaviour that is actually tested in the codebase.
+
+      Guides are grouped by area below and ordered to follow a typical workflow, from
+      the first area through to the last.
+    MARKDOWN
+
+    # Returns a process exit status (0 ok, 1 stale in --check mode).
+    # The bin wrapper passes it straight to exit.
+    def self.run(argv)
+      spec_files = argv - FLAGS
+      generator = new(spec_files.empty? ? nil : spec_files)
+
+      case FLAGS.find { |flag| argv.include?(flag) }
+      when '--check'
+        # Verify docs without running specs; used by CI.
+        generator.up_to_date? ? 0 : 1
+      when '--readme-only'
+        # Rebuild the TOC from committed docs + spec directives only (fast).
+        generator.regenerate_readme
+        0
+      when '--render-only'
+        # Re-render doc bodies from doc comments using screenshots on disk.
+        generator.generate(run_specs: false)
+        0
+      else
+        generator.generate
+        0
+      end
+    end
+
+    def initialize(spec_files = nil)
+      @spec_files = spec_files || find_documented_specs
+    end
+
+    def config
+      AutoPlatformGuide.configuration
+    end
+
+    def generate(run_specs: true)
+      if @spec_files.empty?
+        puts 'No system specs with documentation comments found.'
+        return
+      end
+
+      @spec_files.each do |spec_file|
+        puts "\nGenerating documentation for #{spec_file}..."
+        process_spec(spec_file, run_specs:)
+      end
+
+      generate_readme
+
+      puts "\n✓ Documentation generation complete!"
+      puts "  Generated #{@spec_files.size} documentation file(s) in #{config.generated_docs_dir}/"
+      puts '  Generated README.md with table of contents'
+    end
+
+    # Verify the committed docs are in sync with their documented specs,
+    # without running the specs. Re-renders the doc body and compares against
+    # the committed markdown, ignoring the generation timestamp and the
+    # screenshot binaries themselves. Returns true when everything is up to date.
+    def up_to_date?
+      stale = find_documented_specs.select { |spec_file| doc_stale?(spec_file) }
+
+      if stale.empty?
+        puts '✓ Platform-guide docs are up to date.'
+        return true
+      end
+
+      warn "✗ Platform-guide docs are out of date for #{stale.size} spec(s):"
+      stale.each { |spec_file| warn "  - #{spec_file} -> #{generate_output_filename(spec_file)}" }
+      warn ''
+      warn 'Regenerate the affected guide(s) and commit the result:'
+      stale.each { |spec_file| warn %(  rake "auto_platform_guide:generate[#{spec_file}]") }
+      false
+    end
+
+    # Rebuild only the README table of contents from the committed docs and
+    # their spec `@category`/`@order` directives, without running any specs.
+    def regenerate_readme
+      generate_readme
+      puts '✓ Regenerated README.md table of contents.'
+    end
+
+    private
+
+    def doc_stale?(spec_file)
+      output_file = generate_output_filename(spec_file)
+      return true unless File.exist?(output_file)
+
+      expected = "#{render_doc_body(spec(spec_file).doc_comments, spec(spec_file).screenshot_calls).rstrip}\n"
+      committed = strip_timestamp_header(File.read(output_file, encoding: 'UTF-8'))
+      expected != committed
+    end
+
+    def strip_timestamp_header(content)
+      content.sub(/\A<!--\nGenerated: [^\n]*\n-->\n\n/, '')
+    end
+
+    def find_documented_specs
+      Dir.glob(config.specs_glob).select { |file| spec(file).documented? }
+    end
+
+    # Parsed spec, memoized so a run reads each file once.
+    def spec(spec_file)
+      @specs ||= {}
+      @specs[spec_file] ||= SpecFile.new(spec_file)
+    end
+
+    def process_spec(spec_file, run_specs: true)
+      parsed = spec(spec_file)
+
+      if run_specs
+        puts '  Running spec with SCREENSHOTS=true...'
+        run_spec_with_screenshots(spec_file)
+      else
+        puts '  Re-rendering from doc comments (using existing screenshots)...'
+      end
+
+      # Generate markdown file
+      output_file = generate_output_filename(spec_file)
+      generate_markdown(output_file, parsed.doc_comments, parsed.screenshot_calls)
+
+      puts "  ✓ Generated #{output_file}"
+    end
+
+    def run_spec_with_screenshots(spec_file)
+      FileUtils.mkdir_p(config.screenshots_dir)
+
+      command = "SCREENSHOTS=true bundle exec rspec --format documentation #{spec_file}"
+      system(command, err: File::NULL)
+    end
+
+    def generate_output_filename(spec_file)
+      basename = File.basename(spec_file, '_spec.rb')
+      output_name = "#{basename.upcase.tr('_', '-')}.md"
+      File.join(config.generated_docs_dir, output_name)
+    end
+
+    def generate_markdown(output_file, doc_comments, screenshot_calls)
+      FileUtils.mkdir_p(config.generated_docs_dir)
+      File.write(output_file, "#{timestamp_header}#{render_doc_body(doc_comments, screenshot_calls).rstrip}\n")
+    end
+
+    def timestamp_header
+      "<!--\nGenerated: #{generated_at}\n-->\n\n"
+    end
+
+    def generated_at
+      Time.now.utc.strftime('%Y-%m-%d %H:%M:%S UTC')
+    end
+
+    # Render the markdown body (everything after the timestamp header) from a
+    # spec's doc comments and screenshot calls. Shared by generation and --check
+    # so both produce byte-identical output for the same spec.
+    def render_doc_body(doc_comments, screenshot_calls)
+      body = +''
+
+      doc_comments.each_with_index do |comment, index|
+        heading_tag = "h#{comment[:level]}"
+        heading_id = slugify(comment[:title])
+        body << "<#{heading_tag} id=\"#{heading_id}\">#{comment[:title]}</#{heading_tag}>\n\n"
+
+        comment[:content].each { |line| body << "#{line}\n" }
+        body << "\n"
+
+        next_comment_line = doc_comments[index + 1]&.dig(:line_number) || Float::INFINITY
+        screenshots = find_related_screenshots(comment[:line_number], next_comment_line, screenshot_calls)
+        screenshots.each do |screenshot|
+          rendered = render_screenshot(screenshot[:path])
+          body << rendered if rendered
+        end
+      end
+
+      body
+    end
+
+    def find_related_screenshots(current_line, next_line, screenshot_calls)
+      # Find screenshots that appear after this comment but before the next one
+      screenshot_calls.select do |screenshot|
+        screenshot[:line_number] > current_line && screenshot[:line_number] < next_line
+      end
+    end
+
+    def render_screenshot(screenshot_path)
+      # Only embed screenshots whose generated file exists on disk. Image URLs
+      # mirror screenshots_dir so a customized dir keeps working links.
+      return unless File.exist?(File.join(config.screenshots_dir, "#{screenshot_path}.png"))
+
+      prefix = "/#{config.screenshots_dir.sub(%r{\A/+}, '').sub(%r{/+\z}, '')}"
+      "![#{screenshot_path}](#{prefix}/#{screenshot_path}.png)\n\n"
+    end
+
+    def slugify(text)
+      text.downcase
+          .gsub(/[^a-z0-9\s-]/, '')
+          .gsub(/\s+/, '-').squeeze('-')
+          .gsub(/^-|-$/, '')
+    end
+
+    # Writes the README table of contents grouped by `@category` and ordered by
+    # `@order`. Called at the end of a full/partial generation run and standalone
+    # via `regenerate_readme` (the `--readme-only` mode).
+    def generate_readme
+      readme_path = File.join(config.generated_docs_dir, 'README.md')
+
+      File.open(readme_path, 'w') do |f|
+        f.puts '<!--'
+        f.puts "Generated: #{generated_at}"
+        f.puts '-->'
+        f.puts
+
+        f.write(config.readme_preamble || README_PREAMBLE)
+
+        # Build the TOC from every documented spec (not just the ones regenerated
+        # in this run) so running for a subset of specs doesn't drop other
+        # entries. Group by `@category` and order by `@order`.
+        groups = toc_groups
+
+        f.puts category_workflow_diagram(groups.map(&:first))
+        f.puts
+        f.puts '<h2 id="table-of-contents">Table of Contents</h2>'
+
+        groups.each do |category, entries|
+          f.puts
+          f.puts %(<h3 id="#{slugify(category)}">#{category}</h3>)
+          f.puts
+          entries.each do |entry|
+            f.puts "- [#{entry[:title]}](#{entry[:file]})"
+          end
+        end
+      end
+    end
+
+    # A Mermaid flowchart of the guide categories in workflow order, rendered by
+    # the in-app docs viewer. Derived from the same ordered categories as the TOC,
+    # so it never drifts from the actual guides.
+    def category_workflow_diagram(categories)
+      return '' if categories.empty?
+
+      nodes = categories.each_with_index.map { |category, index| %(c#{index}["#{category}"]) }
+      <<~DIAGRAM.chomp
+
+        ```mermaid
+        flowchart LR
+            #{nodes.join(' --> ')}
+        ```
+      DIAGRAM
+    end
+
+    # Returns the TOC as an ordered list of [category, entries] pairs.
+    # Category order is derived entirely from the specs: categories are
+    # listed in ascending order of the smallest `@order` they contain (ties broken
+    # alphabetically), and entries within a category are ordered by `@order` then
+    # title. Only specs whose generated doc actually exists on disk are linked.
+    def toc_groups
+      entries = find_documented_specs.filter_map do |spec_file|
+        file = File.basename(generate_output_filename(spec_file))
+        next unless File.exist?(File.join(config.generated_docs_dir, file))
+
+        parsed = spec(spec_file)
+        directives = parsed.directives
+        {
+          file:,
+          title: parsed.title,
+          category: directives[:category] || DEFAULT_CATEGORY,
+          order: directives[:order] || DEFAULT_ORDER
+        }
+      end
+
+      entries
+        .group_by { |entry| entry[:category] }
+        .sort_by { |category, group| [group.map { |entry| entry[:order] }.min, category] }
+        .map { |category, group| [category, group.sort_by { |entry| [entry[:order], entry[:title]] }] }
+    end
+  end
+end

data/lib/auto_platform_guide/rake_tasks.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'auto_platform_guide'
+
+module AutoPlatformGuide
+  # Rake task bodies. Tasks themselves are declared below; this module keeps the
+  # exit-status handling testable without invoking rake.
+  module RakeTasks
+    module_function
+
+    def run(argv, failure:)
+      status = Generator.run(argv)
+      return if status.zero?
+
+      abort(failure)
+    end
+  end
+end
+
+namespace :auto_platform_guide do
+  desc 'Generate guides from every documented system spec'
+  task :generate, [:spec_file] do |_task, args|
+    spec_files = [args[:spec_file], *args.extras].compact
+    AutoPlatformGuide::RakeTasks.run(spec_files, failure: 'Guide generation failed')
+  end
+
+  desc 'Verify committed guides match their specs; fails when stale'
+  task :check do
+    AutoPlatformGuide::RakeTasks.run(
+      ['--check'],
+      failure: 'Committed guides are stale; run rake auto_platform_guide:generate'
+    )
+  end
+
+  desc 'Rebuild only the README table of contents'
+  task :readme do
+    AutoPlatformGuide::RakeTasks.run(['--readme-only'], failure: 'README generation failed')
+  end
+
+  desc 'Re-render guides from doc comments, reusing screenshots on disk'
+  task :render do
+    AutoPlatformGuide::RakeTasks.run(['--render-only'], failure: 'Guide rendering failed')
+  end
+end

data/lib/auto_platform_guide/rspec.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object/blank'
+require 'capybara'
+
+module AutoPlatformGuide
+  # RSpec wiring for system specs: a rack_test default, a real browser where a
+  # spec needs one (examples tagged :js, plus every system spec when
+  # SCREENSHOTS=true), doc_screenshot support, and forgery protection.
+  #
+  #   RSpec.configure do |config|
+  #     AutoPlatformGuide.setup_rspec(config)
+  #   end
+  #
+  # The browser driver is configuration.browser_driver (:playwright default,
+  # :selenium supported).
+  module DocScreenshotHelper
+    # Conditional screenshot capture. Enable with: SCREENSHOTS=true rspec spec/...
+    def doc_screenshot(filename)
+      return unless AutoPlatformGuide.screenshots_enabled?
+
+      sleep 0.5 # Allow time for animations to complete
+      save_screenshot(Rails.root.join(AutoPlatformGuide.configuration.screenshots_dir, "#{filename}.png")) # rubocop:disable Lint/Debugger
+    end
+  end
+
+  def self.setup_rspec(config)
+    # A contended machine (CI, or sibling spec:parallel workers) lets async Turbo
+    # Stream deliveries exceed a short wait. Only the slow path lengthens.
+    contended = ci? || ENV.key?('TEST_ENV_NUMBER')
+    max_wait_time = contended ? 10 : 5
+
+    screen_size = ENV.fetch('CAPYBARA_WINDOW_SIZE', '1920,900').split(',').map(&:to_i)
+    browser_options = driver_options(max_wait_time)
+
+    configure_capybara
+
+    Capybara.save_path = './log/capybara'
+
+    config.include DocScreenshotHelper, type: :system
+
+    # rack_test by default, for performance
+    config.before(type: :system) do
+      AutoPlatformGuide.prepare_system_example(self, max_wait_time, screen_size, browser_options)
+    end
+
+    config.around(:each, type: :system) do |example|
+      AutoPlatformGuide.with_forgery_protection(example)
+    end
+
+    config.before(type: :system, js: true) do
+      AutoPlatformGuide.prepare_js_example(self, screen_size, browser_options)
+    end
+  end
+
+  def self.prepare_system_example(example, max_wait_time, screen_size, browser_options)
+    Capybara.default_max_wait_time = max_wait_time
+
+    if screenshots_enabled?
+      drive_with_browser(example, screen_size:, options: browser_options)
+    else
+      example.driven_by(:rack_test)
+    end
+  end
+
+  def self.with_forgery_protection(example)
+    ActionController::Base.allow_forgery_protection = true
+    example.run
+  ensure
+    ActionController::Base.allow_forgery_protection = false
+  end
+
+  def self.prepare_js_example(example, screen_size, browser_options)
+    drive_with_browser(example, screen_size:, options: browser_options)
+    attach_browser_logging(example) if configuration.browser_driver == :playwright
+  end
+
+  def self.configure_capybara
+    Capybara.configure do |capybara|
+      capybara.server_host = ENV.fetch(
+        'CAPYBARA_SERVER_HOST',
+        ci? ? IPSocket.getaddress(Socket.gethostname) : 'localhost'
+      )
+
+      # Different ports per parallel worker to avoid conflicts
+      base_port = ci? ? 3000 : 3500
+      port_offset = ENV['TEST_ENV_NUMBER'].to_i
+      capybara.server_port = base_port + port_offset
+
+      capybara.app_host = ENV.fetch('CAPYBARA_APP_HOST', "http://#{capybara.server_host}:#{capybara.server_port}")
+      capybara.raise_server_errors = false
+    end
+  end
+
+  def self.drive_with_browser(example, screen_size:, options:)
+    case configuration.browser_driver
+    when :playwright
+      example.driven_by(:playwright, screen_size:, options:)
+    when :selenium
+      example.driven_by(:selenium, using: :headless_chrome, screen_size:)
+    else
+      raise ArgumentError, "Unknown browser_driver: #{configuration.browser_driver.inspect}"
+    end
+  end
+
+  # Each example gets a fresh browser context, so web storage cannot leak between them.
+  def self.attach_browser_logging(example)
+    example.page.driver.with_playwright_page do |playwright_page|
+      playwright_page.on('console', lambda { |message|
+        Rails.logger.error("[BROWSER][#{message.type}] #{message.text}") if message.type == 'error'
+      })
+      playwright_page.on('pageerror', lambda { |error|
+        Rails.logger.error("[BROWSER][pageerror] #{error.message}")
+      })
+    end
+  end
+
+  def self.driver_options(max_wait_time)
+    return {} unless configuration.browser_driver == :playwright
+
+    # Keystrokes would otherwise inherit Playwright's own 30s timeout; navigation keeps a
+    # long budget because a click that waits for one is bounded by the action timeout.
+    { default_timeout: max_wait_time, default_navigation_timeout: 30 }
+  end
+
+  def self.ci?
+    ENV['CI'].present?
+  end
+
+  def self.screenshots_enabled?
+    ENV['SCREENSHOTS'] == 'true'
+  end
+end

data/lib/auto_platform_guide/spec_file.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module AutoPlatformGuide
+  # A system spec file carrying `# = Heading` doc comments and
+  # `doc_screenshot('name')` calls. Parses it once and exposes what the
+  # generator needs: headings with their body, screenshots, TOC directives and
+  # the doc title.
+  class SpecFile
+    # One `=` per heading level: `# = Title`, `# == Sub-title`.
+    HEADING = /^\s*#\s*(=+)\s*(.+?)\s*$/
+    # Exactly one space after `#` is the comment prefix; anything beyond it is
+    # content, so indented code inside fenced blocks survives.
+    COMMENT = /^\s*#\s?(.*?)\s*$/
+
+    # `@category` / `@order` control TOC placement only and are stripped from the
+    # body. `@order` is global across guides and categories sort by their
+    # smallest `@order`, so there is no category list to keep in sync.
+    CATEGORY_DIRECTIVE = /^\s*#\s*@category\s+(.+?)\s*$/
+    ORDER_DIRECTIVE = /^\s*#\s*@order\s+(\d+)\s*$/
+    DIRECTIVE = /^\s*#\s*@(?:category|order)\b/
+
+    def initialize(path)
+      @path = path
+    end
+
+    # True when the spec has at least one top-level doc comment.
+    def documented?
+      lines.any? { |line| line.match?(/^#\s*=/) }
+    end
+
+    # Comment blocks in source order: `{ level:, title:, content:, line_number: }`.
+    # A block runs until the next heading or the first non-comment line;
+    # `@category`/`@order` lines are TOC metadata, never body content.
+    def doc_comments
+      @doc_comments ||= parse_doc_comments
+    end
+
+    # `{ path:, line_number: }` for every `doc_screenshot('...')` call.
+    def screenshot_calls
+      @screenshot_calls ||= parse_screenshot_calls
+    end
+
+    # First `@category` / `@order` in the file, or nil.
+    def directives
+      @directives ||= { category: first_match(CATEGORY_DIRECTIVE), order: first_match(ORDER_DIRECTIVE)&.to_i }
+    end
+
+    # The top-level (`# =`, not `# ==`) heading, falling back to the file name.
+    def title
+      @title ||= lines.filter_map { |line| line.match(/^\s*#\s*=(?!=)\s*(.+?)\s*$/)&.[](1)&.strip }
+                      .reject(&:empty?).first ||
+                 File.basename(@path, '_spec.rb').split('_').map(&:capitalize).join(' ')
+    end
+
+    private
+
+    def lines
+      @lines ||= File.readlines(@path, encoding: 'UTF-8')
+    end
+
+    def first_match(pattern)
+      lines.filter_map { |line| line.match(pattern)&.[](1) }.first
+    end
+
+    def parse_doc_comments
+      blocks = []
+      current = nil
+
+      lines.each.with_index(1) do |line, number|
+        next if DIRECTIVE.match?(line)
+
+        if (heading = line.match(HEADING))
+          blocks << current if current
+          title = heading[2].strip
+          # A divider line like `# ==== ` has no title and is not a heading.
+          current = title.empty? ? nil : { level: heading[1].length, title:, content: [], line_number: number }
+        elsif current.nil?
+          next
+        elsif (comment = line.match(COMMENT))
+          current[:content] << comment[1]
+        else
+          blocks << current
+          current = nil
+        end
+      end
+
+      blocks << current if current
+      blocks
+    end
+
+    def parse_screenshot_calls
+      call = %r{doc_screenshot\(['"]([\w\-/]+)['"]\)}
+
+      lines.each.with_index(1).filter_map do |line, number|
+        path = line[call, 1]
+        { path:, line_number: number } if path
+      end
+    end
+  end
+end

data/lib/auto_platform_guide/version.rb

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

data/lib/auto_platform_guide.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'auto_platform_guide/version'
+require 'auto_platform_guide/configuration'
+require 'auto_platform_guide/spec_file'
+require 'auto_platform_guide/document'
+require 'auto_platform_guide/generator'
+require 'auto_platform_guide/docs_controller_actions'
+
+module AutoPlatformGuide
+  def self.load_engine
+    require 'auto_platform_guide/engine' if defined?(Rails::Engine)
+  end
+  private_class_method :load_engine
+end
+
+AutoPlatformGuide.send(:load_engine)

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: auto-platform-guide
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mauricio Zaffari
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.40'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.40'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Generator and spec helpers that turn doc comments and screenshots in
+  system specs into markdown platform guides, plus a markdown docs viewer for Rails
+  admin apps.
+email:
+- mauricio@develoz.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/views/docs/show.html.erb
+- lib/auto-platform-guide.rb
+- lib/auto_platform_guide.rb
+- lib/auto_platform_guide/configuration.rb
+- lib/auto_platform_guide/docs_controller_actions.rb
+- lib/auto_platform_guide/document.rb
+- lib/auto_platform_guide/engine.rb
+- lib/auto_platform_guide/generator.rb
+- lib/auto_platform_guide/rake_tasks.rb
+- lib/auto_platform_guide/rspec.rb
+- lib/auto_platform_guide/spec_file.rb
+- lib/auto_platform_guide/version.rb
+homepage: https://github.com/mauriciozaffari/auto-platform-guide
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mauriciozaffari/auto-platform-guide
+  changelog_uri: https://github.com/mauriciozaffari/auto-platform-guide/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Generate in-app documentation from system specs.
+test_files: []