guard-boondoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9808173acf5b72841dd3acdf32958970df6d11ae1b4c70d23b61d16cb36bfa04
+  data.tar.gz: fc81a22ac53395bf2dab91f67e91c06ca1daf72ddc578f74c3c1c8ff0a63250b
+SHA512:
+  metadata.gz: e8c9dd7d3f8f1e5030d7f25cb1c4b7ed9f75bcbc861cef88f1f6f4d8ade66a72beeb4eda215fc5c783dce59c3b1d130052e23afc97e71f4077e22bd3d9eb3102
+  data.tar.gz: 0b2053246dc6a0318c243fcea83aa3944c62dfd4c16403fb8532991b7b25f927155ad9fd5276ee12a41f35d3e3ca434d00410d2fa2db6043b11002e3782f9e91

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-10-26
+
+### ✨ Features
+- **`guard :boondoc` plugin:** regenerates your Boondoc markdown docs whenever the watched files change.
+- **`status_file` option:** records the outcome of each run.
+- **Guardfile `watch` lines:** these override the files Boondoc would otherwise watch. Changes to the output directory never trigger a regeneration.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Joe Sharp
+
+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,67 @@
+# guard-boondoc
+
+A [Guard](https://github.com/guard/guard) plugin that regenerates your [Boondoc](https://github.com/joe-sharp/boondoc)
+docs when a file Boondoc reads changes.
+
+## Setup
+
+```ruby
+# Gemfile
+group :development do
+  gem 'guard-boondoc'
+end
+```
+
+```sh
+bundle exec guard init boondoc   # adds `guard :boondoc` to your Guardfile
+bundle exec guard
+```
+
+## What it does
+
+The docs are generated when Guard starts, and again whenever one of these changes, is added, or is removed:
+
+- the Ruby files in `sources`
+- the README and the `files` you stitch in
+- the files matching `assets`
+- `.boondoc.yml` and `.yardopts`
+
+What to build comes from Boondoc's own configuration, not from Guardfile options. The plugin reads `.boondoc.yml` and `.yardopts` on every run, so editing them takes effect
+without restarting Guard, and changes inside the output directory never trigger a run.
+
+If Boondoc fails, for example in `strict` mode with warnings, the error is shown and Guard marks the task as
+failed. The next change to a file Boondoc reads tries again.
+
+## Overriding what is watched
+
+If you need to regenerate for files Boondoc doesn't read, or want full control, add your own `watch` lines:
+
+```ruby
+guard :boondoc do
+  watch(%r{^templates/})
+  watch('.boondoc.yml')
+end
+```
+
+Any `watch` turns off the detection described above, so your patterns alone decide when the docs are regenerated.
+Changes inside the output directory still never trigger a run, so a broad pattern such as `/\.md$/` is safe.
+
+## Recording the outcome
+
+To let another tool, such as a status line, see how the last run went, give the plugin a `status_file`:
+
+```ruby
+guard :boondoc, status_file: 'tmp/docs_status.txt'
+```
+
+After each run the file holds `ok`, or `error` followed by Boondoc's message. Its directory is created if needed.
+
+## Development
+
+```sh
+bundle exec rake   # specs and RuboCop
+```
+
+## License
+
+MIT, see [LICENSE.txt](LICENSE.txt).

data/lib/guard/boondoc/templates/Guardfile

@@ -0,0 +1 @@
+guard :boondoc

data/lib/guard/boondoc/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Guard
+  module BoondocVersion
+    VERSION = '0.1.0'
+  end
+end

data/lib/guard/boondoc.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'guard/compat/plugin'
+require 'boondoc'
+require_relative 'boondoc/version'
+
+module Guard
+  # Regenerates boondoc documentation when a file boondoc reads changes.
+  #
+  # What to watch and where the docs go come from `.boondoc.yml` and
+  # `.yardopts`, which are read again on every run. The only option is
+  # `status_file`, a path the outcome of each run is written to: `ok`, or
+  # `error` followed by boondoc's message.
+  #
+  # @example Guardfile
+  #   guard :boondoc
+  #
+  # @example Guardfile, recording each run's outcome
+  #   guard :boondoc, status_file: 'tmp/docs_status.txt'
+  #
+  # @example Guardfile, overriding what is watched
+  #   guard :boondoc do
+  #     watch(%r{^templates/})
+  #   end
+  class Boondoc < Plugin
+    # Files whose change can alter how every other file is read.
+    CONFIG_FILES = [::Boondoc::Config::FILE, '.yardopts'].freeze
+    GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+    # Watches every file, then narrows to the ones boondoc reads when they change,
+    # since those are only known from the configuration. Watchers given in the
+    # Guardfile replace that, and then decide on their own when to regenerate.
+    def initialize(options = {})
+      super
+      @custom_watchers = !watchers.empty?
+      self.watchers = [Guard::Watcher.new(/./)] unless @custom_watchers
+    end
+
+    # @return [void]
+    def start
+      generate
+    end
+
+    # @return [void]
+    def reload
+      generate
+    end
+
+    # @return [void]
+    def run_all
+      generate
+    end
+
+    # @param paths [Array<String>] files that changed, relative to the project
+    # @return [void]
+    def run_on_modifications(paths)
+      paths = outside_output(paths)
+      return if paths.empty?
+
+      generate if @custom_watchers || relevant?(paths)
+    end
+    alias run_on_additions run_on_modifications
+    alias run_on_removals run_on_modifications
+
+    private
+
+    def generate
+      config = ::Boondoc::Config.load
+      ::Boondoc::Generator.new(config).run
+      remember(config)
+      record('ok')
+      Compat::UI.info('boondoc: docs regenerated')
+    rescue ::Boondoc::Error => e
+      record("error #{e.message}")
+      Compat::UI.error("boondoc: #{e.message}")
+      throw :task_has_failed
+    end
+
+    def record(status)
+      path = options[:status_file] or return
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, "#{status}\n")
+    end
+
+    def remember(config)
+      @inputs = inputs(config)
+    end
+
+    def inputs(config)
+      [config.source_files, config.extra_files, config.readme_file].flatten.compact
+    end
+
+    # A file is relevant if boondoc read it last run or would read it now, which
+    # covers files added or removed since. Everything is relevant until a run has
+    # succeeded, and when the configuration cannot be read.
+    def relevant?(paths)
+      return true unless @inputs
+
+      config = ::Boondoc::Config.load
+      known = @inputs | inputs(config)
+      paths.any? { |path| CONFIG_FILES.include?(path) || known.include?(path) || asset?(config, path) }
+    rescue ::Boondoc::Error
+      true
+    end
+
+    def asset?(config, path)
+      return false if in_output?(config, path)
+
+      Array(config.assets).any? { |pattern| File.fnmatch?(pattern, path, GLOB_FLAGS) }
+    end
+
+    # Boondoc's own output must never trigger a run, whatever the watchers match.
+    # When the configuration cannot be read, nothing is known to be output.
+    def outside_output(paths)
+      config = ::Boondoc::Config.load
+      paths.reject { |path| in_output?(config, path) }
+    rescue ::Boondoc::Error
+      paths
+    end
+
+    def in_output?(config, path)
+      output = config.output_dir.delete_prefix(File.join(config.root, ''))
+      path == output || path.start_with?(File.join(output, ''))
+    end
+  end
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: guard-boondoc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joe Sharp
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: boondoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.20'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.20'
+- !ruby/object:Gem::Dependency
+  name: guard-compat
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: guard-boondoc watches the files boondoc reads, as set in .boondoc.yml
+  and .yardopts, and regenerates your markdown documentation when one of them changes.
+email:
+- joesharp13@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/guard/boondoc.rb
+- lib/guard/boondoc/templates/Guardfile
+- lib/guard/boondoc/version.rb
+homepage: https://github.com/joe-sharp/guard-boondoc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/joe-sharp/guard-boondoc
+  source_code_uri: https://github.com/joe-sharp/guard-boondoc/tree/v0.1.0
+  bug_tracker_uri: https://github.com/joe-sharp/guard-boondoc/issues
+  changelog_uri: https://github.com/joe-sharp/guard-boondoc/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.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Guard plugin that regenerates your boondoc docs when their sources change
+test_files: []