yard gems results in [error]: The file `./docs/yard_plugin.rb' could not be loaded:

[aelkoussy]

Steps to reproduce

I run yard gems and it gives the following error:

❯ yard -v
yard 0.9.28
❯ yard gems
[error]: The file `./docs/yard_plugin.rb' could not be loaded:
cannot load such file -- ./docs/yard_plugin.rb

I tried to reinstall ruby/yard/no-cache , and I looked up stackoverflow for the error but no leads at all, I am trying to make it work for Solargraph to provide intellisense for the gems

Thanks for the help

## Environment details:

- OS: MacOS Monterey 12.6
- Ruby version (`ruby -v`): 3.1.2
- YARD version (`yard -v`): 0.9.28
- Relevant software dependency/versions:
  only rbenv

[impepc]

it might be help this workaround
.

[borisrorsvort]

I’ve this exact same issue.

[lsegal]

Given that this is only reproducible with rbenv, I feel like this should be reported upstream to that project.

YARD relies on the $LOAD_PATH and/or working directory(*) being set correctly such that file is visible to load(file) in load_script:

yard/lib/yard/cli/command.rb

Lines 68 to 74 in e167846

	def load_script(file)
	return if YARD::Config.options[:safe_mode]
	load(file)
	rescue LoadError => load_exception
	log.error "The file `#{file}' could not be loaded:\n#{load_exception}"
	exit
	end

In reality we're probably relying on the working directory here: YARD does actually switch the working directory when parsing a specific gem and thus ./docs/yard_plugin.rb should be correctly resolved per standard lookup rules, unless the load method was mangled by rbenv.

Now unfortunately due to a lot of internals about the way load path works (complicated by whether or not Bundler is involved, as well as different versions of rubygems etc), I'm not entirely sure what exactly is not getting set correctly, but based on the lack of reproduction with a standard Ruby install, it seems as though load('./docs/yard_plugin.rb') is indeed properly loading the relative Ruby script at runtime, and thus, this seems specific to rbenv's setting of pwd/LOAD_PATH/etc. The logic to load scripts in YARD dates back to ~2012 and has worked for a decade now, including (this is a guess) in rbenv builds prior to the current one, since is the first time this issue is being reported. I would suspect that either rbenv changed something, or Ruby 3.1 changed some base reality that rbenv was specifically relying on. In either case, This is working in a standard Ruby install.

That said, there are a few other workarounds you can glean from this: the easiest would be to use ruby -I./path/to/yard-gem -S yard gems to set your LOAD_PATH explicitly (you can use gem which yard to get that path). Fortunately once the .yardoc database is built for YARD, solargraph will skip it, so you technically can do this outside of your VS Code / IDE if this is meant to seed your solargraph database.

Another would be to cd into the directory above and type yard gems there. That should most certainly work.

Hope that helps!

(*): Understanding ruby load, require, gems, bundler and rails autoloading from the bottom up

[borisrorsvort]

@lsegal I had this error on 2.7.6. I switched to another project in 2.7.3 and it works fine. Both use rbenv.

[marvingreenberg]

FWIW, on macos with ruby 2.7.4 and rbenv,

❯ ruby --version
ruby 2.7.4p191 (2021-07-07 revision a21a3b7d23) [x86_64-darwin21]
❯ rbenv --version
rbenv 1.2.0
❯ yard --version
yard 0.9.28
❯ gem which yard
/Users/mgreenberg/.rbenv/versions/2.7.4/lib/ruby/gems/2.7.0/gems/yard-0.9.28/lib/yard.rb
❯ find  /Users/mgreenberg/.rbenv/versions -name yard_plugin.rb
❯  ########## nothing found ##########
❯ cd /Users/mgreenberg/.rbenv/versions/2.7.4/lib/ruby/gems/2.7.0/gems/yard-0.9.28
❯ yard gems
[error]: The file `./docs/yard_plugin.rb' could not be loaded:
cannot load such file -- ./docs/yard_plugin.rb

Even following the workaround above and recommendations here, still the same issue.

❯ ruby -I /Users/mgreenberg/.rbenv/versions/2.7.4/lib/ruby/gems/2.7.0/gems/yard-0.9.28 -S yard gems
[error]: The file `./docs/yard_plugin.rb' could not be loaded:
cannot load such file -- ./docs/yard_plugin.rb
❯ cd /Users/mgreenberg/.rbenv/versions/2.7.4/lib/ruby/gems/2.7.0/gems/yard-0.9.28
❯ touch docs/yard_plugin.rb
❯ ruby -I /Users/mgreenberg/.rbenv/versions/2.7.4/lib/ruby/gems/2.7.0/gems/yard-0.9.28 -S yard gems
[error]: The file `./docs/yard_plugin.rb' could not be loaded:
cannot load such file -- ./docs/yard_plugin.rb

And, interestingly, it also works fine for rbenv version 2.7.3 although there is no yard_plugin.rb there either.

OK, it seems to be reek and the workaround does actually fix it.

❯ yard gems --verbose
[info]: Building yardoc index for gem: reek-6.1.4
[error]: The file `./docs/yard_plugin.rb' could not be loaded:
cannot load such file -- ./docs/yard_plugin.rb
❯ gem which reek
/Users/mgreenberg/.rbenv/versions/2.7.4/lib/ruby/gems/2.7.0/gems/reek-6.1.4/lib/reek.rb
❯ mkdir /Users/mgreenberg/.rbenv/versions/2.7.4/lib/ruby/gems/2.7.0/gems/reek-6.1.4/docs
❯ touch /Users/mgreenberg/.rbenv/versions/2.7.4/lib/ruby/gems/2.7.0/gems/reek-6.1.4/docs/yard_plugin.rb

Then, yard gems proceeds past reek and all the other gems, successfully.

[chiperific]

FWIW, I use rvm and was having this same problem.

Using yard gems --verbose exposed that the reek gem was my problem, too. The error made me think the problem was global, not a specific gem.

Doing the same as @marvingreenberg worked for me:

➜ gem which reek                                                                 
/Users/chipkragt/.rvm/gems/ruby-3.1.3/gems/reek-6.1.4/lib/reek.rb
➜ mkdir /Users/chipkragt/.rvm/gems/ruby-3.1.3/gems/reek-6.1.4/docs
➜ touch /Users/chipkragt/.rvm/gems/ruby-3.1.3/gems/reek-6.1.4/docs/yard_plugin.rb

After that, yard gems ran all the way through

[johnhamelink]

I had this same problem, but for me it was with Shoulda Matchers.

I had to run:

rm -f $(bundle show shoulda_matchers)/doc_config/yard/setup.rb
touch $(bundle show shoulda_matchers)/doc_config/yard/setup.rb

[lsegal]

These reports indicate third party issues that should probably be reported in the specific projects.

[lsegal]

Marking this as closed.