result and option

.github/workflows/main.yml

@@ -23,5 +23,5 @@ jobs:
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
-      - name: Run the default task
-        run: bundle exec rake spec
+      - name: Run yard doctest
+        run: bundle exec yard doctest

.rubocop.yml

@@ -0,0 +1 @@
+require: rubocop-yard

.yardopts

@@ -0,0 +1 @@
+--plugin yard-doctest

Gemfile

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in errgonomic.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
+gem 'rake', '~> 13.0', group: :development
+gem 'rspec', '~> 3.0', group: :development
+gem 'rubocop', group: :development
+gem 'rubocop-yard', group: :development
+gem 'solargraph', group: :development
 
-gem "rspec", "~> 3.0"
-
-gem "standard", "~> 1.3"
+# gem "standard", "~> 1.3", group: :development

Gemfile.lock

@@ -1,26 +1,45 @@
 PATH
   remote: .
   specs:
-    errgonomic (0.1.0)
+    errgonomic (0.2.0)
       concurrent-ruby (~> 1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    backport (1.2.0)
+    benchmark (0.4.0)
     concurrent-ruby (1.3.5)
     diff-lcs (1.6.0)
+    jaro_winkler (1.6.0)
     json (2.10.1)
+    kramdown (2.5.1)
+      rexml (>= 3.3.9)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     language_server-protocol (3.17.0.4)
-    lint_roller (1.1.0)
+    logger (1.6.6)
+    mini_portile2 (2.8.8)
+    minitest (5.25.4)
+    nokogiri (1.18.3)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    observer (0.1.2)
+    ostruct (0.6.1)
     parallel (1.26.3)
     parser (3.3.7.1)
       ast (~> 2.4.1)
       racc
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.2.1)
+    rbs (3.8.1)
+      logger
     regexp_parser (2.10.0)
+    reverse_markdown (3.0.0)
+      nokogiri
+    rexml (3.4.1)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -46,35 +65,53 @@ GEM
       unicode-display_width (>= 2.4.0, < 4.0)
     rubocop-ast (1.38.1)
       parser (>= 3.3.1.0)
-    rubocop-performance (1.23.1)
-      rubocop (>= 1.48.1, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+    rubocop-yard (0.10.0)
+      rubocop (~> 1.21)
+      yard
     ruby-progressbar (1.13.0)
-    standard (1.45.0)
-      language_server-protocol (~> 3.17.0.2)
-      lint_roller (~> 1.0)
-      rubocop (~> 1.71.0)
-      standard-custom (~> 1.0.0)
-      standard-performance (~> 1.6)
-    standard-custom (1.0.2)
-      lint_roller (~> 1.0)
-      rubocop (~> 1.50)
-    standard-performance (1.6.0)
-      lint_roller (~> 1.1)
-      rubocop-performance (~> 1.23.0)
+    solargraph (0.52.0)
+      backport (~> 1.2)
+      benchmark
+      bundler (~> 2.0)
+      diff-lcs (~> 1.4)
+      jaro_winkler (~> 1.6)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.1)
+      logger (~> 1.6)
+      observer (~> 0.1)
+      ostruct (~> 0.6)
+      parser (~> 3.0)
+      rbs (~> 3.0)
+      reverse_markdown (>= 2.0, < 4)
+      rubocop (~> 1.38)
+      thor (~> 1.0)
+      tilt (~> 2.0)
+      yard (~> 0.9, >= 0.9.24)
+      yard-solargraph (~> 0.1)
+    thor (1.3.2)
+    tilt (2.6.0)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
+    yard (0.9.37)
+    yard-doctest (0.1.17)
+      minitest
+      yard
+    yard-solargraph (0.1.0)
+      yard (~> 0.9)
 
 PLATFORMS
-  arm64-darwin-24
   ruby
 
 DEPENDENCIES
   errgonomic!
   rake (~> 13.0)
   rspec (~> 3.0)
-  standard (~> 1.3)
+  rubocop
+  rubocop-yard
+  solargraph
+  yard (~> 0.9)
+  yard-doctest (~> 0.1)
 
 BUNDLED WITH
    2.5.22

Rakefile

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
 
+require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
-require "standard/rake"
+require 'yard/doctest/rake'
+YARD::Doctest::RakeTask.new do |task|
+  task.doctest_opts = %w[-v]
+  task.pattern = 'lib/**/*.rb'
+end
 
-task default: %i[spec standard]
+task default: %i[spec yard:doctest]

bin/console

@@ -1,11 +1,11 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require "errgonomic"
+require 'bundler/setup'
+require 'errgonomic'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

doctest_helper.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'lib/errgonomic'

errgonomic.gemspec

@@ -1,21 +1,26 @@
 # frozen_string_literal: true
 
-require_relative "lib/errgonomic/version"
+# when we build in the nix store, version.rb is hashed and adjacent to the gemspec
+if __FILE__.include?('/nix/store') && (version_file = Dir.glob('./*-version.rb').first)
+  require_relative version_file
+else
+  require_relative 'lib/errgonomic/version'
+end
 
 Gem::Specification.new do |spec|
-  spec.name = "errgonomic"
+  spec.name = 'errgonomic'
   spec.version = Errgonomic::VERSION
-  spec.authors = ["Nick Zadrozny"]
-  spec.email = ["nick@onemorecloud.com"]
+  spec.authors = ['Nick Zadrozny']
+  spec.email = ['nick@onemorecloud.com']
 
-  spec.summary = "Opinionated, ergonomic error handling for Ruby, inspired by Rails and Rust."
+  spec.summary = 'Opinionated, ergonomic error handling for Ruby, inspired by Rails and Rust.'
   spec.description = "Let's blend the Rails 'present' and 'blank' conventions with a few patterns from Rust Option types."
-  spec.homepage = "https://omc.io/"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.0.0"
+  spec.homepage = 'https://omc.io/'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/omc/errgonomic"
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/omc/errgonomic'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -26,14 +31,16 @@ Gem::Specification.new do |spec|
         f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
     end
   end
-  spec.bindir = "exe"
+  spec.bindir = 'exe'
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
   # Uncomment to register a new dependency of your gem
   # spec.add_dependency "example-gem", "~> 1.0"
 
-  spec.add_dependency "concurrent-ruby", "~> 1.0"
+  spec.add_dependency 'concurrent-ruby', '~> 1.0'
+  spec.add_development_dependency 'yard', '~> 0.9'
+  spec.add_development_dependency 'yard-doctest', '~> 0.1'
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

flake.nix

@@ -15,13 +15,6 @@
         "aarch64-darwin"
       ];
       overlays = [
-        (final: prev: {
-          gems = final.bundlerEnv {
-            name = "errgonomic";
-            gemdir = ./.;
-            # src = final.lib.cleanSource ../.;
-          };
-        })
       ];
       forAllSystems =
         f:
@@ -36,12 +29,25 @@
     {
       devShells = forAllSystems (
         { pkgs, ... }:
+        let
+          inherit (pkgs) ruby bundix;
+        in
         {
           default = pkgs.mkShell {
             buildInputs = [
-              pkgs.ruby
-              pkgs.bundix
-              pkgs.gems
+              ruby
+              bundix
+              (pkgs.bundlerEnv {
+                name = "errgonomic";
+                gemdir = ./.;
+                extraConfigPaths = [
+                  ./errgonomic.gemspec
+                  ./lib/errgonomic/version.rb
+                ];
+                postInstall = ''
+                  find . >&2
+                '';
+              })
             ];
           };
         }