Add support for context blocks in HTML index

[greggroth]

Right now, all examples under a resource are flattened to a single list, so tests that have the same example name across different contexts to highlight different behaviors lose this organization. For example, given a test like:

resource "Blog" do
  get "/blog/:client_id" do
    context "as the page owner" do
      before { sign_in }

      example_request "responds with 200" do
        expect(status).to eq 200
      end
    end

    context "as a visitor" do
      example_request "responds with 200" do
        expect(status).to eq 200
      end
    end
  end
end

Would generate docs structured like

Blog
  - responds with 200
  - responds with 200

So the request detail GET /blog/:client and the context of each example are left out.

This can be worked around with more verbose example descriptions, but would y'all be open to considering an update to the HTML doc writer to include the structure of the tests so the index output is more like

Blog
  - GET /blog/:client_id
    - as a page owner
      - responds with 200
    - as a visitor
      - responds with 200

[jakehow]

@greggroth sounds good to me, even better if it can be flipped on via a flag to preserve existing behavior for now.

[greggroth]

👍 I'll try to find time to hack on this in the coming weeks and will keep a configuration option in mind. Thank you!

[PhilT]

I've hit this issue as well and there's actually even more to this. Example requests with the same description get overwritten in the generated files.

post '/orders' do
  example_request 'responds with 200' do
  end
end

get '/orders' do
  example_request 'responds with 200' do
  end
end

Outputs 2 identically named files called orders/responds_with_200.