Question: Build Yard docs upon gem installation?

[thomthom]

I know you can configure Yard to build docs upon all gem installations.

But I was wondering if it was possible for a gem itself to control whether this happened?

The background is that I have a set of Ruby API stubs to provide code insight for IDEs. With VSCode one can use the Solargraph gem. It makes use of Yard to provide some of the code insight - it picks up types from the doc comments.

However, right now one have to manually trigger YARD to build the docs when installing or updating. yard gems sketchup-api-stubs
Apart from making Yard build for all gems (which I'd prefer not to - most I don't need docs for), is there a way to make a gem trigger yard documentation upon installation? I found some references to has_rdoc = 'yard' - but that appear to be deprecated and removed.

[lsegal]

YARD supports RubyGems' --document flag:

https://github.com/lsegal/yard/blob/5deb08c329c0609429c2b8670ff139eb7a446635/CHANGELOG.md#091---july-18th-2016

• Added support for RubyGems 2.x --document=yri,yard flags. You can now run
  YARD documentation generation against installed gems by running:
  gem install mygem --document=yard,yri.

You can configure that globally in your gemrc. YARD also added a metadata override for gemspecs:

https://github.com/lsegal/yard/blob/5deb08c329c0609429c2b8670ff139eb7a446635/CHANGELOG.md#092---july-19th-2016

• Added yard config --gem-install-[yri|yard] commands which auto-configure
  your ~/.gemrc file to run yri/yard instead of ri/rdoc on a gem install.
• Added support for gemspec metadata key "yard.run", which can be either
  "yard" or "yri" to run the respective commands on a gem install.

Hope that helps!

[thomthom]

? Added support for gemspec metadata key "yard.run", which can be either
"yard" or "yri" to run the respective commands on a gem install.

I'm not that familiar with crafting gems (still leaning). Does the above mean I'd add something like this to my gemspec file?

  spec.metadata = {
    'yard.run' => 'yard'
  }

And that should trigger YARD to build docs for that gem when its installed/updated?

[thomthom]

I've been testing. When I added the snipped above it did indeed generate the docs.

But it took a lot longer than yard gems sketchup-api-stubs. Upon further investigation, without the metadata above, when I run yard gems sketchup-api-stubs then only .yardoc appear to be generated.

For the purpose of the API stub gem - for use with Solargraph - that is precisely what I need.

So maybe I should moderate my question; upon installation of my gem, can I trigger YARD to generate only the .yardoc directory with the object database?

[thomthom]

Oooh.... I just discovered what YRI does!

And this is what I needed for the gem:

  spec.metadata = {
    'yard.run' => 'yri'
  }

Sidenote, YRI is very interesting. Is there a way to search for a module/class/method without having the full qualified identifier path? For instance; yri find #foobar and if it only finds that method in a single object, display that. If there are multiple matches, display a list.
If nothing like that exist, can YRI be extended by another gem or template to add commands? If not, would you be interested in a PR that add search to YRI?

[thomthom]

I'm running into problems where yri has not been run for my gem. Is 'yard.run' => 'yri' only for gem install or does it also work for bundle install?

I've had a few times where I have had to run yard gems sketchup-api-stubs for the YRI data to be generated.

(The YRI data is used by Solargraph to provide code insight in VSCode.)

[lsegal]

Keep in mind that YARD respects --no-document, so if you're using this on your system you will not get docs generated on gem install. I can't speak to Bundler's behavior regarding doc installs, but YARD hooks into auto-doc support via RubyGems, so if Bundler is skipping RubyGems for installation then that would be outside of YARD's supported path.

[thomthom]

I typically use wither gem install without any flags or Bundler. I'll dig closer at what happens when bundle installs the gems.

Maybe I need to look for a way to force YRI to alway run regardless of --no-document flags - since the whole purpose of the stub library is to be available for IDE code insight.

Is there any way to debug/log/verbose when YRI is suppose to run as part of gem install? Have you done any such thing during development of Yard?

[lsegal]

I believe that running gem with its respective debug flags should give you information about which plugins get loaded, but tldr any gem with a lib/rubygems_plugin.rb file will be loaded when RubyGems runs.

Unfortunately YARD won't provide a way to force doc generation to run regardless of user settings, since users need to be able to fully control how gems get installed on their machines.

The fix here might be for Solargraph to take on, namely maybe that project should be providing a plugin to auto-index all gems after a successful gem installation. Or perhaps this can be coupled with a notification to VS Code to initiate such an action so that it only works when you're running in a development context. Basically, Solargraph should not assume that indexing has been performed on a gem install, nor should it expect a user has this configured.

[thomthom]

Yea - it might be something that can be done on the side of Solargraph. A while back when I was using RubyMine it "just worked" - so this is rather exclusive to Solargraph.