Deja vu: http://markmail.org/message/fooegs3x4ggsm5d3
I'm +1. We need to see how the pubsub thing with the site will work. I'd love to get rid of the svnpubsub we use now and move to Git there too. Martin Grigorov Wicket Training and Consulting https://twitter.com/mtgrigorov On Mon, Nov 3, 2014 at 2:20 PM, Martijn Dashorst <[email protected] > wrote: > 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 >
