Currently we generate our awesome reference documentation using gdoc, which was developed to generate groovy? and grails documentation. However groovy has migrated to asciidoctor and from what I have heard grails is following suit.
As I am familiar with asciidoctor due to work related documentation efforts I did a trial migration for one chapter of the reference guide. The idea is to make this a module of Wicket (6.x, 7.x and 8.x) and have the example code actually be runnable as a project and have the documentation reference (parts of) the example code. This way we can make sure our documentation and code are in sync and that folks copy/pasting example code have a decent shot of it working in one go. You can find the trial project here: https://github.com/dashorst/wicketguide And a generated example here: http://dashorst.github.io/wicketguide/ An example of a document that includes live code: https://github.com/dashorst/wicketguide/blob/master/src/main/asciidoc/ajax/ajaxbehaviours.adoc The live code that is included: https://github.com/dashorst/wicketguide/blob/master/src/main/java/org/apache/wicket/guide/ajax/behavior/HomePage.java I know that it is a lot of work to convert documentation, and there are still some buts and ifs (like how to incorporate this in our site, have a multi-page html generation, the in the README mentioned include bug, or how to automate the conversion in a reasonable way). I find the idea of executable and executing example code rather enticing and I'd like to see if more folks see this happening. This would mean more work than just a plain conversion as we need to get (most of) the examples in working order (not all examples are intended to compile, just to show a concept). What do you think? Martijn
