Re: Future of GDoc

[Andrea Del Bene]

+2 :-). gdoc is very limited and, to me, not well documented. For 
example, it does not even support footnotes.
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