Custom handler for RSpec tests?

[emiltin]

Hi, I'm trying to write an extension that will document my rspec tests. Eg,

RSpec.describe "Aggregated status" do
  # Test aggregated status request, by sending a request
  # and verifying that an aggregated status is received.
  it 'responds to aggregated status request', version: '>=3.1.5' do |example|
    # do stuff
  end
end

I'm looking at https://yardoc.org/guides/extending-yard/writing-handlers.html but feel stuck. I'm trying something like this:

class RSpecSpecificationHandler < YARD::Handlers::Ruby::Base
  handles method_call(:it)      # this seems to work for method calls, but not the rspec 'it'
  def process
    # what goes in here?
  end
end

Are there any examples or pointers that can help me, or do you have some tips? I found this very old repo https://github.com/burtlo/yard-rspec, but it seems it was not working even back then.

[emiltin]

I've looked at existing plugins, but only found things 10+ year old, and haven't been able to get any of them to generate anything.

Can anyone help me with a small working example, or tell me why my attempt above doesn't work?

[emiltin]

Looking more at https://github.com/lsegal/yard-spec-plugin I got it to generate something. But it seems to to assume that specs are linked to a specific instance method, and are nested inside an rspec descibe() block.

My use case is very simple, as described above: rspec it() blocks documented with a comment. The specs are not linked to a class or method.

[emiltin]

I've worked more with the yard-rspec plugin and think I understand a bit more.

One thing I don't understand is how I can add a new main section in the resulting html. I would like RSpec tests to show up under a new main section called eg. "Specifications", not only as part of methods documentation, because my tests are not linked to instance methods.

Do I need to create a new subclass of CodeObject or can I just work with the template system?