Hey Martin, Great initiative!
The gendocs script is a workaround for a bug in the asciidoctor-maven-plugin when you use section includes from XML files. If you didn't use those, the generation works fine. With 1.5.2 this should be solved according to the asciidoctor folks. I am going to try an automated approach to transcoding the gdocs to asciidoctor format. Transcoding 226 pages manually is not my cup of tea. From there we can go in and fix formatting issues, use actual includes etc. I have been looking at several projects at apache and it appears we are not the only ones trying to do this: http://mail-archives.apache.org/mod_mbox/deltaspike-dev/201408.mbox/%3CCAAxZHdd8VQL3CZSwbg9Xeexdm5uevNDwAZ6Hbtvd=Ptkp2=z...@mail.gmail.com%3E So this seems to be a good approach. Martijn On Sun, Nov 30, 2014 at 8:20 PM, Martin Funk <[email protected]> wrote: > Hi Martijn, > > taking your suggestion, my pick on this can be found here: > https://github.com/mafulafunk/wicket/tree/user-guide-6 > Most of the contribution can be found in the wicket-user-guide subdir > > I just dug through the first 4 Chapters, to get my own feel for it. > > Things that work: > -the asciidoctor generation works using mvn (something get generated) > > Things I'm not sure about or haven't tested yet: > -where to place the example source code > -haven't tested the gendocs.sh > -internal cross references > -code block insertions from other files > [...] > > I'm not all that unsatisfied with it, so I'll try to let it grow the next > days. > > Any help and feedback welcome, > > Martin > >> Am 03.11.2014 um 13:20 schrieb Martijn Dashorst <[email protected]>: >> >> 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 > -- Become a Wicket expert, learn from the best: http://wicketinaction.com
