Provide a custom Asciidoctor macro that reduces the boilerplate required to include snippets

The basic idea is that rather than using an include for each individual snippet, you can use a single macro to include all of the snippets for a particular operation that’s been documented. For added flexibility, the macro could use attributes to control which snippets are included.

I prototyped this a while ago as a custom target for the include macro: https://github.com/wilkinsona/springrestdocs/commit/6657af0d590be2673f05d7ecd8f1a91244751edc. I think this could be further refined so that it becomes something like operation::{snippets}/operation-name.

[meistermeier]

Thanks @mojavelinux , somehow I was mixing up options and attributes.

For now I have the Ruby based extension running included in the spring-restdocs-asciidoctor module and used in one of the samples and it is including static input. Next stop: loading snippets.

Btw. the same approach also works with Java but feels “not so right”. Maybe I will show both ones in the end.

[mojavelinux]

Aha. The problem is that right now, the parse_content method assumes it’s only dealing with non-section content. Upon reflection, this feels like a bad assumption. But we’ll have to deal with it upstream.

If what you are parsing includes sections, you have 3 options:

1. Use lower-level APIs to parse both sections and block content
2. Parse the content as a standalone document, then import the nodes from that AST
3. Use discrete section titles (aka headings)

I don’t think you really want (3), and (1) is way too risky. So let’s focus on (2).

process do |parent, reader, attrs|
  content = %q(before

=== Subsection

Some more content)
  doc = parent.document
  fragment = Asciidoctor.load content,
      safe: doc.options[:safe],
      attributes: { 'fragment' => '' }
  fragment.blocks.each do |b|
    b.parent = parent
    parent << b
  end
  nil
end

The fragment attribute is important because it informs the parser that the source is a document fragment and should not be validated as a standalone document. Specifically, this allows the top-level section titles to start at any level.

It’s clear we need a method in the extensions API that performs a similar operation. That method would also be careful to carry over all processor options so that the parser is operating with the same configuration. But this code is sufficient portable for your needs, I think.