sdoc_live 0.1.13 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5650fe4d2019c3e87194df2b3991e1353be042296fb48d4d6401832981aae200
-  data.tar.gz: 0a2aa835270a49e4e053e7c6e43de03cab05c335ce1bf3f28633d7db82bf7ce1
+  metadata.gz: e430a8c15b61ce23a122b5b69b45bdee182c67067bd22e06379f369dbc888348
+  data.tar.gz: 6d15cc569f162076e03ed12464dd097845ce25af526a07c88c1c188ee26534d5
 SHA512:
-  metadata.gz: d3370cd47fb6b9c436cf25f4b2da691c6da616bc225039393887be61133b8e20a7ca00b3bc107eba25fff09d906e8e164c0f859668fc29457141fada77960cf5
-  data.tar.gz: 0aee08711b0940fe269167b1e583b4578884d25c72b596cd7810be10e1bdcf4daeede3bed516bf033fccb4e805c548d8227409a1a2daf20afbbe7ef2e88f9a34
+  metadata.gz: a0172e9fcd45479f579491b084d07ff0bc7804bb1c4c539effea3d6d97417d0fec325dc6390e07a64841b327fe38389aa5cff012176fdf9cb5497e7dea550445
+  data.tar.gz: 12ba4c7955a9b5da5bb329cb444557f1e4aec6eead864c76f193540d788ea50a9b6658e2fe44764aa722880e6427d10c78c984c6b02848ac20856dac5c0666c9

data/README.md

@@ -1,9 +1,11 @@
 # SDoc Live
 
-Live SDoc generation for Rails — watches your source files and auto-regenerates API documentation on changes. Serves docs via a mountable engine at a path you choose (e.g. `/doc`).
+Live SDoc generation for Rails — watches your source files and auto-regenerates API documentation on changes. Serves docs via Rack middleware at a configurable path (default: `/doc`).
 
 ## Requirements
 
+- Ruby >= 3.2
+- Rails >= 7.0
 - **SDoc** gem (included as a dependency)
 
 ## Installation
@@ -24,9 +26,26 @@ Then run `bundle install`.
 > end
 > ```
 
+## Quick Start
+
+1. Add the gem to your Gemfile and run `bundle install`
+2. Add the Puma plugin to `config/puma.rb`:
+
+```ruby
+if ENV.fetch("RAILS_ENV", "development") == "development"
+  plugin :sdoc_live
+end
+```
+
+3. Start your Rails server and visit `/doc`
+
+That's it — documentation is generated automatically and rebuilds when you change any `.rb` file in `app/` or `lib/`.
+
 ## Usage
 
-### 1. Puma Plugin (Development Watch Mode)
+### Puma Plugin (Development Watch Mode)
+
+The Puma plugin is the primary way to use SDoc Live in development. It forks a child process that generates documentation on boot and watches for file changes.
 
 Add to your `config/puma.rb`:
 
@@ -36,18 +55,37 @@ if ENV.fetch("RAILS_ENV", "development") == "development"
 end
 ```
 
-This watches `app/` and `lib/` for `.rb` file changes and automatically regenerates SDoc documentation.
+The plugin provides:
+
+- **Automatic generation** on Puma boot
+- **File watching** via the `listen` gem — regenerates docs when `.rb` files change
+- **Lifecycle management** — the SDoc process stops when Puma stops, and vice versa
+
+### Rake Task (Manual / CI / Deploy)
 
-### 2. Rake Task (Manual / Deploy)
+For one-off generation without file watching:
 
 ```bash
 rake sdoc:build
 ```
 
+This is useful for CI pipelines or production deployments where you want to pre-generate documentation.
+
+## Serving Documentation
+
+SDoc Live automatically inserts Rack middleware that serves generated documentation at the configured `mount_path` (default: `/doc`). No route mounting is needed — it works out of the box.
+
+- `GET /doc` redirects to `/doc/`
+- `GET /doc/` serves the documentation index
+- `GET /doc/...` serves any generated documentation file
+
+The middleware is inserted before `Rails::Rack::Logger`, so documentation requests don't appear in your Rails logs.
+
 ## Configuration
 
+Create an initializer at `config/initializers/sdoc_live.rb`:
+
 ```ruby
-# config/initializers/sdoc_live.rb
 SdocLive.configure do |config|
   # Title for the generated documentation (default: "Documentation")
   config.title = "My App API"
@@ -72,16 +110,46 @@ SdocLive.configure do |config|
 
   # URL path where documentation is served (default: "/doc")
   # config.mount_path = "/doc"
+
+  # Cache-Control header for served documentation files (default: "no-cache")
+  # Use "no-cache" in development to always get fresh docs.
+  # Use "public, max-age=3600" in production for better performance.
+  # config.cache_control = "public, max-age=3600"
 end if defined?(SdocLive)
 ```
 
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `title` | `"Documentation"` | HTML title for the generated docs |
+| `main_file` | `"README.md"` | File displayed on the docs landing page |
+| `source_dirs` | `["app", "lib"]` | Directories scanned by RDoc for source files |
+| `watch_dirs` | `nil` (falls back to `source_dirs`) | Directories watched for file changes in dev mode |
+| `watch_file_type_regex` | `/\.rb$/` | File pattern that triggers regeneration |
+| `output_dir` | `nil` (defaults to `tmp/doc`) | Where generated HTML documentation is written |
+| `rdoc_options` | `nil` | Additional CLI options passed to RDoc/SDoc |
+| `mount_path` | `"/doc"` | URL path where documentation is served |
+| `cache_control` | `"no-cache"` | `Cache-Control` header for served files |
+
 ## How It Works
 
-1. **Development**: Puma boots → forks a child process that runs `SdocLive::Generator#build_watch`
-2. The `listen` gem monitors `app/` and `lib/` for `.rb` file changes
-3. On change, SDoc regenerates documentation into `tmp/doc/`
-4. Docs are served via middleware at the configured `mount_path` (default: `/doc`)
-5. Clean subprocess management with bidirectional lifecycle monitoring (Puma ↔ SDoc)
+```
+Rails app boots
+├── Engine initializer inserts StaticFiles middleware
+│   └── Serves tmp/doc/ at /doc (before Rails logger)
+└── Puma plugin forks child process
+    ├── Generator#build runs full SDoc generation → tmp/doc/
+    ├── Listen gem watches app/ + lib/ for .rb changes
+    └── On change → Generator#build again (full regeneration)
+```
+
+1. **Boot**: When Rails starts, the `SdocLive::Engine` initializer inserts `SdocLive::StaticFiles` Rack middleware that serves files from the output directory
+2. **Generate**: The Puma plugin forks a child process that runs a full SDoc build
+3. **Watch**: The child process uses the `listen` gem to monitor source directories for file changes
+4. **Rebuild**: When a matching file changes, the generator runs a complete SDoc rebuild with `--force-output`
+5. **Serve**: The middleware serves documentation files using `ActionDispatch::FileHandler`, handling path prefixing and trailing slash redirects
+6. **Lifecycle**: Bidirectional process monitoring ensures the SDoc child process and Puma stay in sync — if either dies, the other is stopped
 
 ## License
 

data/lib/puma/plugin/sdoc_live.rb

@@ -1,9 +1,21 @@
 require "puma/plugin"
 
+# Puma plugin that runs SDoc Live in a forked child process during development.
+#
+# Activated by adding <tt>plugin :sdoc_live</tt> to +config/puma.rb+.
+#
+# After Puma boots, it forks a child that calls
+# +SdocLive::Generator#build_watch+ (initial build + file watching).
+# Bidirectional lifecycle monitoring ensures both processes stay in sync:
+#
+# - If Puma dies, the SDoc child exits.
+# - If the SDoc child dies, Puma is stopped.
 Puma::Plugin.create do
 
   attr_reader :puma_pid, :sdoc_pid, :log_writer
 
+  # Called by Puma during plugin registration. Sets up the forked SDoc
+  # process after boot and registers a shutdown hook.
   def start(launcher)
     @log_writer = launcher.log_writer
     @puma_pid = $PROCESS_ID
@@ -42,6 +54,7 @@ Puma::Plugin.create do
 
   private
 
+  # Sends INT to the SDoc child process and waits for it to exit.
   def stop_sdoc
     Process.waitpid(sdoc_pid, Process::WNOHANG)
     log "Stopping SdocLive..."
@@ -50,14 +63,18 @@ Puma::Plugin.create do
   rescue Errno::ECHILD, Errno::ESRCH
   end
 
+  # Monitors the Puma parent process from the SDoc child.
   def monitor_puma
     monitor(:puma_dead?, "Detected Puma has gone away, stopping SdocLive...")
   end
 
+  # Monitors the SDoc child process from the Puma parent.
   def monitor_sdoc
     monitor(:sdoc_dead?, "Detected SdocLive has gone away, stopping Puma...")
   end
 
+  # Polls +process_dead+ every 2 seconds. When the monitored process is
+  # detected as dead, logs the message and sends INT to the current process.
   def monitor(process_dead, message)
     loop do
 
@@ -71,6 +88,7 @@ Puma::Plugin.create do
     end
   end
 
+  # Returns +true+ if the SDoc child process has exited.
   def sdoc_dead?
     Process.waitpid(sdoc_pid, Process::WNOHANG)
     false
@@ -78,6 +96,7 @@ Puma::Plugin.create do
     true
   end
 
+  # Returns +true+ if the Puma parent process has been replaced (i.e. died).
   def puma_dead?
     Process.ppid != puma_pid
   end

data/lib/sdoc_live/engine.rb

@@ -1,37 +1,63 @@
 module SdocLive
 
+  # Rails engine that registers the SdocLive::StaticFiles middleware and
+  # loads the +sdoc:build+ rake task. No route mounting is required — the
+  # middleware is inserted automatically before +Rails::Rack::Logger+ so
+  # documentation requests don't appear in application logs.
   class Engine < ::Rails::Engine
 
     rake_tasks do
       load File.expand_path("../tasks/sdoc_live.rake", __dir__)
     end
 
+    # Inserts the StaticFiles middleware using the current SdocLive configuration.
     initializer "sdoc_live.static" do
       config = SdocLive.configuration
       doc_root = (config.output_dir || Rails.root.join("tmp", "doc")).to_s
       mount_path = config.mount_path
+      cache_control = config.cache_control
 
       Rails.application.middleware.insert_before(
         Rails::Rack::Logger,
         SdocLive::StaticFiles,
         doc_root,
-        mount_path
+        mount_path,
+        cache_control
       )
     end
 
   end
 
+  # Rack middleware that serves generated SDoc files from +doc_root+ at the
+  # configured +mount_path+. Uses +ActionDispatch::FileHandler+ for efficient
+  # file serving with configurable +Cache-Control+ headers.
+  #
+  # == Behavior
+  #
+  # - +GET /doc+ → 301 redirect to +/doc/+
+  # - +GET /doc/...+ → serves matching file from +doc_root+, or falls through
+  #   to the Rails app if no file matches
   class StaticFiles
 
-    def initialize(app, doc_root, mount_path)
+    # Initializes the middleware.
+    #
+    # [app]           The next Rack app in the middleware stack.
+    # [doc_root]      Absolute path to the directory containing generated docs.
+    # [mount_path]    URL prefix where docs are served (e.g. +"/doc"+).
+    # [cache_control] Value for the +Cache-Control+ response header.
+    #                 Default: +"no-cache"+.
+    def initialize(app, doc_root, mount_path, cache_control = "no-cache")
       @app = app
       @mount_path = mount_path.chomp("/")
       @file_handler = ActionDispatch::FileHandler.new(
         doc_root,
-        headers: { "cache-control" => "public, max-age=3600" }
+        headers: { "cache-control" => cache_control }
       )
     end
 
+    # Handles an incoming Rack request. Redirects bare mount path to trailing
+    # slash, attempts to serve a file for paths under the mount path, and
+    # falls through to the next middleware otherwise.
     def call(env)
       path_info = env["PATH_INFO"]
 
@@ -52,4 +78,4 @@ module SdocLive
 
   end
 
-end
+end

data/lib/sdoc_live/generator.rb

@@ -2,8 +2,16 @@ require "fileutils"
 
 module SdocLive
 
+  # Generates SDoc documentation from Ruby source files. Wraps +RDoc::RDoc+
+  # with SDoc formatting and supports both one-shot builds and continuous
+  # watch-mode regeneration.
   class Generator
 
+    # Creates a new generator.
+    #
+    # [root] Project root directory. Defaults to +Rails.root+ when available,
+    #        otherwise +Dir.pwd+. All configured paths are resolved relative
+    #        to this root.
     def initialize(root: nil)
       @root = root || defined?(Rails) && Rails.root || Pathname.new(Dir.pwd)
       @root = Pathname.new(@root) unless @root.is_a?(Pathname)
@@ -25,6 +33,9 @@ module SdocLive
       @rdoc_options          = config.rdoc_options
     end
 
+    # Runs a full SDoc generation pass into the configured output directory.
+    # Uses <tt>--force-output</tt> to overwrite any existing docs. Prints
+    # elapsed time on completion.
     def build
       start_time = Time.now
 
@@ -57,6 +68,11 @@ module SdocLive
       puts "[SdocLive] Generated in #{ format('%.2f', elapsed) }s → #{ @output_dir }"
     end
 
+    # Builds documentation once, then watches +watch_dirs+ for file changes
+    # matching +watch_file_type_regex+ and rebuilds on each change. Blocks
+    # the current thread until interrupted.
+    #
+    # This is the method called by the Puma plugin in a forked child process.
     def build_watch
       require "listen"
 

data/lib/sdoc_live/version.rb

@@ -1,5 +1,5 @@
 module SdocLive
 
-  VERSION = "0.1.13"
+  VERSION = "0.1.15"
 
 end

data/lib/sdoc_live.rb

@@ -1,25 +1,56 @@
 require_relative "sdoc_live/version"
 
+# Live SDoc generation for Rails. Watches source files and auto-regenerates
+# API documentation on changes, serving it via Rack middleware.
+#
+# == Quick Start
+#
+#   # config/initializers/sdoc_live.rb
+#   SdocLive.configure do |config|
+#     config.title = "My App API"
+#   end if defined?(SdocLive)
+#
+# See Configuration for all available options.
 module SdocLive
 
   class << self
 
     attr_writer :configuration
 
+    # Returns the current configuration, initializing with defaults if needed.
     def configuration
       @configuration ||= Configuration.new
     end
 
+    # Yields the current Configuration for modification.
+    #
+    #   SdocLive.configure do |config|
+    #     config.title = "My Docs"
+    #     config.source_dirs = ["app", "lib", "engines"]
+    #   end
     def configure
       yield(configuration)
     end
 
   end
 
+  # Holds all configuration options for SDoc Live.
+  #
+  # == Attributes
+  #
+  # [output_dir]             Where generated HTML is written. Default: +Rails.root.join("tmp", "doc")+.
+  # [title]                  HTML title for generated docs. Default: +"Documentation"+.
+  # [main_file]              Landing page source file. Default: +"README.md"+.
+  # [source_dirs]            Directories scanned by RDoc. Default: <tt>["app", "lib"]</tt>.
+  # [watch_dirs]             Directories watched for changes (falls back to +source_dirs+). Default: +nil+.
+  # [watch_file_type_regex]  File pattern that triggers regeneration. Default: +/\.rb$/+.
+  # [rdoc_options]           Additional CLI options passed to RDoc/SDoc. Default: +nil+.
+  # [mount_path]             URL path where docs are served. Default: +"/doc"+.
+  # [cache_control]          Cache-Control header value for served files. Default: +"no-cache"+.
   class Configuration
 
     attr_accessor :output_dir, :title, :main_file, :source_dirs, :watch_dirs,
-                  :watch_file_type_regex, :rdoc_options, :mount_path
+                  :watch_file_type_regex, :rdoc_options, :mount_path, :cache_control
 
     def initialize
       @source_dirs = ["app", "lib"]
@@ -27,6 +58,7 @@ module SdocLive
       @title = "Documentation"
       @main_file = "README.md"
       @mount_path = "/doc"
+      @cache_control = "no-cache"
     end
 
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sdoc_live
 version: !ruby/object:Gem::Version
-  version: 0.1.13
+  version: 0.1.15
 platform: ruby
 authors:
 - 16554289+optimuspwnius@users.noreply.github.com