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:
1 2 3 4 5 6 7 8 9 10 11 | // File: Sample.groovypackage com.mrhaki.blog.groovyclass Sample { // tag::helloMethod[] String hello() { 'Asciidoc rules!' } // end::helloMethod[]} |
In our Asciidoc document we use the following syntax to include only the hello() method:
1 2 3 4 5 6 | == 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:
1 2 3 4 5 6 7 8 9 10 11 | <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.
