Yard fails to load the gem

[QuentinLemCode]

Hello, there is an issue with this gem when trying to execute yard :

[info]: Building yardoc index for gem: friendly_id-5.5.0
bundler: failed to load command: yard (/home/quentinlem/.rbenv/versions/3.2.1/bin/yard)
guide.rb:7:in `comments_from': undefined method `[]' for nil:NilClass (NoMethodError)
        from guide.rb:14:in `block (2 levels) in <top (required)>'
        from guide.rb:13:in `each'
        from guide.rb:13:in `block in <top (required)>'
        from guide.rb:11:in `open'
        from guide.rb:11:in `<top (required)>'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/command.rb:70:in `load'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/command.rb:70:in `load_script'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/command.rb:28:in `block in common_options'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1694:in `block in parse_in_order'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1636:in `catch'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1636:in `parse_in_order'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1630:in `order!'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1739:in `permute!'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1764:in `parse!'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/command.rb:56:in `parse_options'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/yardoc.rb:536:in `optparse'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/yardopts_command.rb:97:in `parse_yardopts'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/yardopts_command.rb:41:in `parse_arguments'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/yardoc.rb:292:in `parse_arguments'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/yardoc.rb:248:in `run'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/command.rb:14:in `run'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/gems.rb:41:in `block (2 levels) in build_gems'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/gems.rb:39:in `chdir'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/gems.rb:39:in `block in build_gems'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/gems.rb:29:in `each'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/gems.rb:29:in `build_gems'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/gems.rb:21:in `run'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/command.rb:14:in `run'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/command_parser.rb:72:in `run'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/lib/yard/cli/command_parser.rb:54:in `run'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.28/bin/yard:13:in `<top (required)>'
        from /home/quentinlem/.rbenv/versions/3.2.1/bin/yard:25:in `load'
        from /home/quentinlem/.rbenv/versions/3.2.1/bin/yard:25:in `<top (required)>'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/cli/exec.rb:58:in `load'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/cli/exec.rb:58:in `kernel_load'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/cli/exec.rb:23:in `run'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/cli.rb:491:in `exec'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/vendor/thor/lib/thor/command.rb:27:in `run'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/vendor/thor/lib/thor/invocation.rb:127:in `invoke_command'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/vendor/thor/lib/thor.rb:392:in `dispatch'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/cli.rb:34:in `dispatch'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/vendor/thor/lib/thor/base.rb:485:in `start'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/cli.rb:28:in `start'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/bundler-2.4.6/libexec/bundle:45:in `block in <top (required)>'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/3.2.0/bundler/friendly_errors.rb:117:in `with_friendly_errors'
        from /home/quentinlem/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/bundler-2.4.6/libexec/bundle:33:in `<top (required)>'
        from /home/quentinlem/.rbenv/versions/3.2.1/bin/bundle:25:in `load'
        from /home/quentinlem/.rbenv/versions/3.2.1/bin/bundle:25:in `<main>'

[stevecondylios]

I had a similar error message when running yard gems:

guide.rb:7:in `comments_from': undefined method `[]' for nil:NilClass (NoMethodError)
    from guide.rb:14:in `block (2 levels) in <top (required)>'
    from guide.rb:13:in `each'
    from guide.rb:13:in `block in <top (required)>'
    from guide.rb:11:in `open'
    from guide.rb:11:in `<top (required)>'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/command.rb:70:in `load'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/command.rb:70:in `load_script'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/command.rb:28:in `block in common_options'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1694:in `block in parse_in_order'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1636:in `catch'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1636:in `parse_in_order'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1630:in `order!'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1739:in `permute!'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/3.2.0/optparse.rb:1764:in `parse!'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/command.rb:56:in `parse_options'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/yardoc.rb:536:in `optparse'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/yardopts_command.rb:97:in `parse_yardopts'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/yardopts_command.rb:41:in `parse_arguments'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/yardoc.rb:292:in `parse_arguments'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/yardoc.rb:248:in `run'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/command.rb:14:in `run'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/gems.rb:41:in `block (2 levels) in build_gems'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/gems.rb:39:in `chdir'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/gems.rb:39:in `block in build_gems'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/gems.rb:29:in `each'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/gems.rb:29:in `build_gems'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/gems.rb:21:in `run'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/command.rb:14:in `run'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/command_parser.rb:72:in `run'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/lib/yard/cli/command_parser.rb:54:in `run'
    from /Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/yard-0.9.32/bin/yard:13:in `<top (required)>'
    from /Users/st/.rbenv/versions/3.2.1/bin/yard:25:in `load'
    from /Users/st/.rbenv/versions/3.2.1/bin/yard:25:in `<main>'

Looks like the file guide.rb file causes the problem.

I ran find ~/ -name 'guide.rb' to find its location.

find ~/ -name 'guide.rb'
/Users/st//.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/friendly_id-5.5.0/guide.rb
/Users/st//.rbenv/versions/3.0.3/lib/ruby/gems/3.0.0/gems/friendly_id-5.5.0/guide.rb
/Users/st//.rbenv/versions/3.0.3/lib/ruby/gems/3.0.0/gems/friendly_id-5.4.2/guide.rb

It shows I have three separate friendly_id gems on my system, for different ruby versions, so I deleted two older ones I didn't need anymore with:

rm -rf /Users/st//.rbenv/versions/3.0.3/lib/ruby/gems/3.0.0/gems/friendly_id-5.5.0
rm -rf /Users/st//.rbenv/versions/3.0.3/lib/ruby/gems/3.0.0/gems/friendly_id-5.4.2

Then yard gems succeeded.

Hope it helps.

[stevecondylios]

Actually, that worked for yard gems on my system gems, but when I tried it in a rails app directory (for an app using friendly_id 5.5) it failed again with the same error.

I opened the location of the gem and commented out the whole of the guide.rb file, and yard gems seems to succeed now.

For me the location was

/Users/st/.rbenv/versions/3.2.1/lib/ruby/gems/3.2.0/gems/friendly_id-5.5.0/guide.rb 

but it might differ depending on the ruby version in use.

[QuentinLemCode]

For me the path is the following :

/home/quentinlem/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/friendly_id-5.5.0/guide.rb

I haven't separate versions of this gem on my system. Also, commenting the file solve the issue.

The question now is : how to solve this ? Can we update guide.rb to behave differently inside rails or bundle project ?

[amiel]

After a little troubleshooting, I think I've found the source of the issue.

For some context guide.rb attempts to create Guide.md by concatenating the main comment from each of a set of files. It assumes that each of these files has a =begin...=end section.

However, after https://github.com/norman/friendly_id/commit/81442a69df30a604e63fbbd789ba22464de5c758#diff-25bc55f30c705a8a66eb2e7e68071f870583553019da95beaba7ad0518a09793L8, none of these files have a =begin...=end section, as standard suggests using normal comments instead.

The exception comes when attempting to index the first match when there is no match:

 match = File.read(path).match(/\n=begin(.*)\n=end/m)[1].to_s
                                                     ^

Note that it is not just yard doc that is broken by this. The rake guide task that calls this file is also broken for the same reason.

I'm not entirely sure what the best way to move forward is, but with some guidance on a direction I'd be happy to resolve this.

Here are some suggestions:

• Remove rake guide and guide.rb (and remove references from .yardopts)

  I imagine it is worth keeping the guide for the generated yard docs, but I thought I'd include this as it is an option.

• Update the regex to build Guide.md more sophisticated

  This will take a little bit of research, as I'm not entirely sure if this will work as it did before, but I'm thinking that finding the first comment block in each file might work, or at least be a good starting point.

• Use a custom delimiter

  Instead of =begin and =end, this could be # @guide begin and # @guide end.

  Using the custom tag @guide begin would prevent yard from showing the begin and end markers.

• Go back to using =begin...=end comment blocks

  I see 2 ways to do this:

  • Configure rubocop to allow block comments

  Unfortunately, standard doesn't allow customizing the configuration (that's kind of the idea). However, it is possible to use the standard ruleset with rubocop and then customize the rubocop configuration (see https://github.com/standardrb/standard#running-standards-rules-via-rubocop).

  • Use # rubocop:disable Style/BlockComments

  This could be done before each =begin...=end block. Then # rubocop:enable Style/BlockComments would be added after the =end.

[amiel]

I took a stab at resolving this with the custom delimiter idea: #1006