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
