You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@wicket.apache.org by Martin Funk <ma...@gmail.com> on 2014/12/07 19:23:48 UTC

Re: Future of GDoc

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 <ma...@gmail.com>:
> 
> 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=zKQ@mail.gmail.com%3E
> 
> So this seems to be a good approach.
> 
> Martijn
> 
> On Sun, Nov 30, 2014 at 8:20 PM, Martin Funk <ma...@gmail.com> 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 <ma...@gmail.com>:
>>> 
>>> 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


Re: Future of GDoc

Posted by Martijn Dashorst <ma...@gmail.com>.
The guys at asciidoctor have created a transformation tool for
markdown to asciidoctor. I wonder if we can use that to write a
transformer for the wiki markup into asciidoctor.

https://github.com/bodiam/markdown-to-asciidoc

Martijn

On Sun, Dec 7, 2014 at 7:23 PM, Martin Funk <ma...@gmail.com> wrote:
> 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 <ma...@gmail.com>:
>>
>> 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=zKQ@mail.gmail.com%3E
>>
>> So this seems to be a good approach.
>>
>> Martijn
>>
>> On Sun, Nov 30, 2014 at 8:20 PM, Martin Funk <ma...@gmail.com> 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 <ma...@gmail.com>:
>>>>
>>>> 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
>



-- 
Become a Wicket expert, learn from the best: http://wicketinaction.com