sdoc_live 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 55e49cf8d368ca829d746abd1038fbfbc6e93cae8fa12a96e0a9c0afa072ea8b
+  data.tar.gz: 947f0bd79a515516e1288375812314c1bb15529ef25c68ccafca93cdcc379cd9
+SHA512:
+  metadata.gz: 8a5724323180f8c3b0c3182609ecbfd43502bfb4ec40d5a65f92c8d28df0a8bc34d1e956ead8a048fe1add718685f1aaf895b6857a801a48fbf13962fec148dd
+  data.tar.gz: ff75942af57a3d5c5a8a057be1df2fd99aa796614bea43d965ed4c2bf794fb740819bca5918348dda7cc54cfd7954d7a5f5de7d983ae5bbbd9682e177022da91

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,79 @@
+# SDoc Live
+
+Live SDoc generation for Rails — watches your source files and auto-regenerates API documentation on changes. Serves docs from `public/doc/` so they're available at `/doc/index.html` in development.
+
+## Requirements
+
+- **SDoc** gem (included as a dependency)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "sdoc_live"
+```
+
+Then run `bundle install`.
+
+## Usage
+
+### 1. Puma Plugin (Development Watch Mode)
+
+Add to your `config/puma.rb`:
+
+```ruby
+if ENV.fetch("RAILS_ENV", "development") == "development"
+  plugin :sdoc
+end
+```
+
+This watches `app/` and `lib/` for `.rb` file changes and automatically regenerates SDoc documentation.
+
+Docs are served at `/doc/index.html` via Rails' `public/` directory.
+
+### 2. Rake Task (Manual / Deploy)
+
+```bash
+rake sdoc:build
+```
+
+## Configuration
+
+```ruby
+# config/initializers/sdoc_live.rb
+SdocLive.configure do |config|
+  # Title for the generated documentation (default: "Documentation")
+  config.title = "My App API"
+
+  # Main file displayed on the docs landing page (default: "README.md")
+  config.main_file = "README.md"
+
+  # Directories to scan for Ruby source files (default: ["app", "lib"])
+  config.source_dirs = ["app", "lib"]
+
+  # Directories to watch for changes in dev mode (defaults to source_dirs)
+  # config.watch_dirs = ["app", "lib"]
+
+  # Regex for file types that trigger regeneration (default: /\.rb$/)
+  # config.watch_file_type_regex = /\.(rb|md)$/
+
+  # Override the output directory (default: Rails.root.join("public", "doc"))
+  # config.output_dir = Rails.root.join("public", "doc")
+
+  # Additional RDoc options passed to the SDoc generator
+  # config.rdoc_options = ["--all", "--hyperlink-all"]
+end
+```
+
+## 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 `public/doc/`
+4. Docs are immediately available at `/doc/index.html`
+5. Clean subprocess management with bidirectional lifecycle monitoring (Puma ↔ SDoc)
+
+## License
+
+[MIT](LICENSE.txt) — Copyright (c) 2026

data/lib/puma/plugin/sdoc.rb

@@ -0,0 +1,92 @@
+require "puma/plugin"
+
+class Sdoc
+end
+
+Puma::Plugin.create do
+
+  attr_reader :puma_pid, :sdoc_pid, :log_writer
+
+  def start(launcher)
+    @log_writer = launcher.log_writer
+    @puma_pid = $PROCESS_ID
+
+    launcher.events.on_booted do
+
+      @sdoc_pid = fork do
+
+        Thread.new { monitor_puma }
+
+        begin
+          trap("INT") { exit 0 }
+          trap("TERM") { exit 0 }
+
+          require "sdoc_live"
+          generator = SdocLive::Generator.new
+          generator.build_watch
+        rescue => e
+          @log_writer.log "SdocLive error: #{ e.message }"
+          @log_writer.log e.backtrace.join("\n")
+          exit 1
+        end
+
+      end
+
+      in_background do
+
+        monitor_sdoc
+
+      end
+
+    end
+
+    launcher.events.on_stopped { stop_sdoc }
+  end
+
+  private
+
+  def stop_sdoc
+    Process.waitpid(sdoc_pid, Process::WNOHANG)
+    log "Stopping SdocLive..."
+    Process.kill(:INT, sdoc_pid) if sdoc_pid
+    Process.wait(sdoc_pid)
+  rescue Errno::ECHILD, Errno::ESRCH
+  end
+
+  def monitor_puma
+    monitor(:puma_dead?, "Detected Puma has gone away, stopping SdocLive...")
+  end
+
+  def monitor_sdoc
+    monitor(:sdoc_dead?, "Detected SdocLive has gone away, stopping Puma...")
+  end
+
+  def monitor(process_dead, message)
+    loop do
+
+      if send(process_dead)
+        log message
+        Process.kill(:INT, $PROCESS_ID)
+        break
+      end
+      sleep 2
+
+    end
+  end
+
+  def sdoc_dead?
+    Process.waitpid(sdoc_pid, Process::WNOHANG)
+    false
+  rescue Errno::ECHILD, Errno::ESRCH
+    true
+  end
+
+  def puma_dead?
+    Process.ppid != puma_pid
+  end
+
+  def log(...)
+    log_writer.log(...)
+  end
+
+end

data/lib/sdoc_live/engine.rb

@@ -0,0 +1,11 @@
+module SdocLive
+
+  class Engine < ::Rails::Engine
+
+    rake_tasks do
+      load File.expand_path("../tasks/sdoc_live.rake", __dir__)
+    end
+
+  end
+
+end

data/lib/sdoc_live/generator.rb

@@ -0,0 +1,84 @@
+require "fileutils"
+
+module SdocLive
+
+  class Generator
+
+    def initialize(root: nil)
+      @root = root || defined?(Rails) && Rails.root || Pathname.new(Dir.pwd)
+      @root = Pathname.new(@root) unless @root.is_a?(Pathname)
+
+      config = SdocLive.configuration
+
+      @output_dir = config.output_dir || @root.join("public", "doc")
+      @title      = config.title
+      @main_file  = config.main_file
+
+      @source_dirs = (config.source_dirs || ["app", "lib"]).map { @root.join(it).to_s }
+
+      @watch_dirs = (config.watch_dirs || config.source_dirs || ["app", "lib"]).map do
+        path = @root.join(it)
+        path.exist? ? path : nil
+      end.compact
+
+      @watch_file_type_regex = config.watch_file_type_regex
+      @rdoc_options          = config.rdoc_options
+    end
+
+    def build
+      start_time = Time.now
+
+      require "sdoc"
+      require "rdoc/rdoc"
+
+      main_file = @root.join(@main_file)
+
+      args = [
+        "--format", "sdoc",
+        "--output", @output_dir.to_s,
+        "--title", @title,
+        "--force-output",
+        "--quiet"
+      ]
+
+      args.push("--main", main_file.to_s) if main_file.exist?
+
+      if @rdoc_options
+        args.concat(@rdoc_options)
+      end
+
+      args.push(main_file.to_s) if main_file.exist?
+      args.concat(@source_dirs.select { File.directory?(it) })
+
+      rdoc = RDoc::RDoc.new
+      rdoc.document(args)
+
+      elapsed = Time.now - start_time
+      puts "[SdocLive] Generated in #{ format('%.2f', elapsed) }s → #{ @output_dir }"
+    end
+
+    def build_watch
+      require "listen"
+
+      build
+
+      puts "[SdocLive] Starting watch mode..."
+
+      listener = Listen.to(*@watch_dirs, only: @watch_file_type_regex) do | modified, added, _removed |
+        next if (modified + added).empty?
+
+        puts "[SdocLive] Detected changes, regenerating..."
+        build
+      end
+
+      listener.start
+
+      loop { sleep 1 }
+    rescue Interrupt
+      puts "[SdocLive] Watch stopped"
+      listener&.stop
+    end
+
+  end
+
+end

data/lib/sdoc_live/version.rb

@@ -0,0 +1,5 @@
+module SdocLive
+
+  VERSION = "0.1.0"
+
+end

data/lib/sdoc_live.rb

@@ -0,0 +1,36 @@
+require_relative "sdoc_live/version"
+
+module SdocLive
+
+  class << self
+
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+  end
+
+  class Configuration
+
+    attr_accessor :output_dir, :title, :main_file, :source_dirs, :watch_dirs,
+                  :watch_file_type_regex, :rdoc_options
+
+    def initialize
+      @source_dirs = ["app", "lib"]
+      @watch_file_type_regex = /\.rb$/
+      @title = "Documentation"
+      @main_file = "README.md"
+    end
+
+  end
+
+end
+
+require_relative "sdoc_live/generator"
+require_relative "sdoc_live/engine" if defined?(Rails)

data/lib/tasks/sdoc_live.rake

@@ -0,0 +1,13 @@
+namespace :sdoc do
+
+  desc "Generate SDoc documentation"
+  task :build do
+    require "sdoc_live"
+
+    generator = SdocLive::Generator.new
+    generator.build
+
+    puts "SDoc build completed successfully!"
+  end
+
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: sdoc_live
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- 16554289+optimuspwnius@users.noreply.github.com
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: sdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Watches your app and lib directories for Ruby file changes and automatically
+  regenerates SDoc documentation. Includes a Puma plugin for development watch mode
+  and a rake task for manual/deploy builds.
+email:
+- 16554289+optimuspwnius@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/puma/plugin/sdoc.rb
+- lib/sdoc_live.rb
+- lib/sdoc_live/engine.rb
+- lib/sdoc_live/generator.rb
+- lib/sdoc_live/version.rb
+- lib/tasks/sdoc_live.rake
+homepage: https://github.com/optimuspwnius/sdoc-live
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/optimuspwnius/sdoc-live
+  source_code_uri: https://github.com/optimuspwnius/sdoc-live
+  changelog_uri: https://github.com/optimuspwnius/sdoc-live/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+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.7
+specification_version: 4
+summary: Live SDoc generation for Rails — auto-regenerates API documentation on file
+  changes.
+test_files: []