With slow, but hopefully steady, pace I kept on working on transforming the
wicket user guide.
Currently all *.gdoc files are renamed to *.adoc and they are included into
index.adoc.
So all previous gdoc files should be somehow visible in the generated html.
Quite a lot of things are still broken, but at least the document is already
recognizable.
The lowest hanging fruits for me were:
- the import of the *.png and their visiblity in the html
- property rendering of the code blocks
But there are still lots of low hanging fruits left.
I opened up a issue list on github:
https://github.com/mafulafunk/wicket/issues/
Any pull request, help, new issues and advice are welcome.
The code can for the asciidoc can be found in the user-guide-6 branch or my
wicket fork.
https://github.com/mafulafunk/wicket/tree/user-guide-6
The global build should render the html but a simple "mvn" in the
wicket-user-guide folder should be
fine too.
Martin
> Am 30.11.2014 um 20:42 schrieb Martijn Dashorst <[email protected]>:
>
> 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
