search

lsegal / yard

YARD is a Ruby Documentation tool. The Y stands for "Yay!"
http://yardoc.org
MIT License
1.94k stars 397 forks source link

Question: yard plugin creation #1402

Closed LRFalk01 closed 5 days ago

LRFalk01 commented 2 years ago

I've been looking for a guide or walkthrough on how to create yard plugins, and have come up empty. The docs give a high level overview on the basics, but do not really go over how to actually create a plugin or how to test them.

I'd be very thankful for any blog/video/doc links I may have missed that cover plugins in more detail.

lsegal commented 2 years ago

YARD has guides on the website that walk through the process, both for building parsers and for custom templates (your plugin can do one or ther other, or even both): https://yardoc.org/guides

If it's not fully explained there, you can peruse yard doc help to see how to activate plugins (packaged RubyGems) or custom code (.rb files not part of an explicit plugin).

For example code, you can look at existing plugins as an example of how to build package and publish them. You can even look at YARD's own use of custom code in the docs/ directory of this repository.

As far as testing goes, this should be no different than testing any other Ruby component. Since plugins are effectively just added or modified YARD objects, you can also look at YARD's own tests to see how we do it there. Testing is going to depend entirely on what exactly you're building, so it's hard to provide specific instruction here except that YARD should not require any custom tooling to test, though if you are generating HTML content as part of your plugin, you may want to pull in some HTML specific testing tools.

Hope that all helps!