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

[wilkinsona]

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.

[capncodewash]

This would be very useful.

[meistermeier]

@wilkinsona can you take a look at the link? I get a 404. If you don't mind I could take care of this (if we exclude the "automagical" path detection ;) )

Update: Link to prototype code wilkinsona@6657af0

[meistermeier]

Now I finally got some time to think about this issue and playing around with some possible solutions. I don't think that a "one-include-includes-all" approach fits the rest-docs use-case but introducing categories / operations groups (no better naming found) additional to explicit named snippets might be a useful option.

include::restdocs:index-example[category='response']

would be the same as (just as an example)

include::restdocs:index-example[snippets='response-fields, curl-request, http-response']

What is your opinion?

[wilkinsona]

I think it could be a useful option, but I'd prefer to tackle it separately and use the snippets attribute as a starting point.

[meistermeier]

In contrast to the initial idea to use a block macro processor to provide the possibility to use operation::{snippets}/operation-name I kept using the include processor. The problem with converting raw input manually and missing ouput/backend format information mentioned in gh-297 still exists in asciidoctorj.

[wilkinsona]

Ideally, I'd like to implement this as a block macro. I spoke to @mojavelinux about it a few months ago and Dan thought it should be possible but I never figured out how to do it. I thought I'd realised it was possible using the Ruby-based API but while trying to refresh my memory today I think that may have just been wishful thinking.

@mojavelinux do you have any cycles available to help us out here? In a nutshell, I'd like to be able to provide a block macro (or anything else that's similarly concise) that produces these lines automatically.

[meistermeier]

May you have a look at this diff: master...meistermeier:block_macro

I can now use srd::index-example[snippets=response-fields,http-response] (master...meistermeier:block_macro#diff-fa264ba69ca4e20ed2df763d8cc57074R13) to include the both defined snippets.

Creating a new Asciidoctor instance and remove all registered extensions for converting the snippets helped a lot. (master...meistermeier:block_macro#diff-c21f76d1d4ce6afa2781db5b77fc3f31R46)

As you see this is just a quick solution (some println etc.) and needs some more code love and level attribute feature. If you think that this is a possible way to go, I will create a new or update the open pull request.

[wilkinsona]

Creating a new Asciidoctor instance and remove all registered extensions for converting the snippets helped a lot.

Intriguing. What does removing all the registered extensions do? Does it address the problem of potentially getting HTML output in a PDF?

[meistermeier]

Unfortunately I currently cannot determine if this problem still exists. The new instance creation with unregistering all extensions solved a problem related to the directory resolver (every include render failed because it could not resolve the projectdir).
Another strange problem I noticed was that the asciidoctor instance could not be created just once for the instance but has to be done in the process method. Tests or usage of the processor just hang somewhere and the cpu utilisation ramps up to infinity. ;)
Right now I am struggling with some warnings and somehow failing imports from asciidoctor. After that I hope I can give a detailed comment.