asciidoc has this neat feature where you can include a file between two markers.

i used this in a project so the example code was in a separate file that compiles by itself. then the documentation includes regions of the example file via those markers. the net result is that the examples are built as part of the module testing and so the documentation can't get out of date.