Writing technical documentation with Asciidoc and Asciidoctor is so much fun. Especially the include macro makes inserting changing content, like source files, a breeze. We only need to maintain the original source file and changes will automatically appear in the generated documentation. We can include only a part of source file using tags. In the source file we add a comment with the following format tag::tagName[] to start the section. We end the section with end::tagName[]. Now in our Asciidoc document we can indicatie the tags we want to include with include::sourceFile[tags=tagName].
Suppose we have the following Groovy source file Sample.groovy. We want to include the method hello() in our technical documentation:
// File: Sample.groovy
package com.mrhaki.blog.groovy
class Sample {
// tag::helloMethod[]
String hello() {
'Asciidoc rules!'
}
// end::helloMethod[]
}
In our Asciidoc document we use the following syntax to include only the hello() method:
== Sample Asciidoc [source,groovy] .Sample.groovy ---- include::Sample.groovy[tags=helloMethod] ----
This will result in the following HTML if we use Asciidoctor with the pretty-print syntax highlighter:
<div class="listingblock">
<div class="title">Sample.groovy</div>
<div class="content">
<pre class="prettyprint groovy language-groovy"><code>
String hello() {
'Asciidoc rules!'
}
</code>
</pre>
</div>
</div>
</div>
Written with Asciidoctor 0.1.4.
