result and option

.yardopts

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

Gemfile

@@ -6,7 +6,6 @@ source "https://rubygems.org"
 gemspec
 
 gem "rake", "~> 13.0"
-
 gem "rspec", "~> 3.0"
-
 gem "standard", "~> 1.3"
+gem "solargraph"

Gemfile.lock

@@ -8,19 +8,41 @@ 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)
+    nokogiri (1.18.3-arm64-darwin)
+      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)
@@ -50,6 +72,25 @@ GEM
       rubocop (>= 1.48.1, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
     ruby-progressbar (1.13.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)
     standard (1.45.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
@@ -62,19 +103,29 @@ GEM
     standard-performance (1.6.0)
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.23.0)
+    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)
+  solargraph
   standard (~> 1.3)
+  yard (~> 0.9)
+  yard-doctest (~> 0.1)
 
 BUNDLED WITH
    2.5.22

Rakefile

@@ -6,5 +6,11 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 require "standard/rake"
+require "yard/doctest/rake"
 
 task default: %i[spec standard]
+
+YARD::Doctest::RakeTask.new do |task|
+  task.doctest_opts = %w[-v]
+  task.pattern = 'lib/**/*.rb'
+end

doctest_helper.rb

@@ -0,0 +1 @@
+require_relative "lib/errgonomic"

errgonomic.gemspec

@@ -1,6 +1,12 @@
 # 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"
@@ -34,6 +40,8 @@ Gem::Specification.new do |spec|
   # spec.add_dependency "example-gem", "~> 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
+                '';
+              })
             ];
           };
         }