Wicket
  1. Wicket
  2. WICKET-5321

Incorporate Wicket Guide into website

    Details

    • Type: Bug Bug
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 6.13.0
    • Component/s: site
    • Labels:
      None

      Description

      Andrea del Bene has donated the Wicket Guide to the Apache Software Foundation. This issue will track the progress into incorporating the document into our website.

      1. Wicket free guide.odt
        2.84 MB
        Martijn Dashorst
      2. Wicket free guide_asf.odt
        2.85 MB
        Andrea Del Bene
      3. grails-generator.zip
        3.20 MB
        Andrea Del Bene

        Activity

        Hide
        Martijn Dashorst added a comment -

        This file was sent to me by Andrea on July 8, 2013.

        Show
        Martijn Dashorst added a comment - This file was sent to me by Andrea on July 8, 2013.
        Hide
        Andrea Del Bene added a comment -

        File updated with the Apache License 2.0. I didn't inserted the full license but just the header. Let me know if the full license is required.

        Show
        Andrea Del Bene added a comment - File updated with the Apache License 2.0. I didn't inserted the full license but just the header. Let me know if the full license is required.
        Hide
        Martin Grigorov added a comment - - edited

        What is needed to move this task to completion ?

        I suggest to attach a zip with the new sources (the one that generates the HTML). Then we can put the generated HTMLs at https://svn.apache.org/repos/asf/wicket/common/site/trunk. Since the generator is not based on Jekyll we can commit the raw (non-HTML) files somewhere else (either Git or SVN) and just copy the generated HTML files in wicket/common/site/trunk/_site/guide/ folder. This way the guide will be available at http://wicket.apache.org/guide.
        It is not the simplest setup but we can automate the process with a Shell script or something.

        Andrea Del Bene: Please attach the new sources as an archive and I'll do the rest.

        Show
        Martin Grigorov added a comment - - edited What is needed to move this task to completion ? I suggest to attach a zip with the new sources (the one that generates the HTML). Then we can put the generated HTMLs at https://svn.apache.org/repos/asf/wicket/common/site/trunk . Since the generator is not based on Jekyll we can commit the raw (non-HTML) files somewhere else (either Git or SVN) and just copy the generated HTML files in wicket/common/site/trunk/_site/guide/ folder. This way the guide will be available at http://wicket.apache.org/guide . It is not the simplest setup but we can automate the process with a Shell script or something. Andrea Del Bene : Please attach the new sources as an archive and I'll do the rest.
        Hide
        Paul Bors added a comment -

        There are couple of proof reads pending on the Wicket Guide's issues list on Google Code.

        Mainly Issue 18 and few other small typos.

        Once this is incorporated, should Andrea Del Bene take down the Google Code site so people won't get confused?
        Or is that guide different from the one on this ticket?

        Show
        Paul Bors added a comment - There are couple of proof reads pending on the Wicket Guide's issues list on Google Code. Mainly Issue 18 and few other small typos. Once this is incorporated, should Andrea Del Bene take down the Google Code site so people won't get confused? Or is that guide different from the one on this ticket?
        Hide
        Martin Grigorov added a comment -

        It is the same guide. Just the text format is different/better.
        At GoogleCode you can download PDF that is exported from OpenOffice document.
        The new format is something based on http://grails.org/doc/2.3.x/ref/Command%20Line/doc.html (AFAIK). So it should be much easier to apply patches/Pull Requests from the community.
        And yes, I agree that the Google Code project should be deprecated (big red text explaining that the project has moved).

        Show
        Martin Grigorov added a comment - It is the same guide. Just the text format is different/better. At GoogleCode you can download PDF that is exported from OpenOffice document. The new format is something based on http://grails.org/doc/2.3.x/ref/Command%20Line/doc.html (AFAIK). So it should be much easier to apply patches/Pull Requests from the community. And yes, I agree that the Google Code project should be deprecated (big red text explaining that the project has moved).
        Hide
        Andrea Del Bene added a comment -

        Martin has anticipated what I wanted to write. As soon as the guide will be available on apache server, I will make clear on GoogleCode that the project is moved away. In the meantime I won't publish any update on the original site to avoid any confusion.
        I'm preparing to load the code, I will notify you when I'm done.

        Show
        Andrea Del Bene added a comment - Martin has anticipated what I wanted to write. As soon as the guide will be available on apache server, I will make clear on GoogleCode that the project is moved away. In the meantime I won't publish any update on the original site to avoid any confusion. I'm preparing to load the code, I will notify you when I'm done.
        Hide
        Andrea Del Bene added a comment -

        I've attached the source. To generate the documentation extract the content and run 'grails doc' on the content root.

        Show
        Andrea Del Bene added a comment - I've attached the source. To generate the documentation extract the content and run 'grails doc' on the content root.
        Hide
        Martin Grigorov added a comment -

        Downloaded Grails 2.3.0.
        Unzipped it in ~/devel/grails-2.3.0.
        $ export PATH=$PATH:~/devel/grails-2.3.0/bin
        /tmp/grails-generator $ grails doc
        Configuring classpath

        Error Resolve error obtaining dependencies: Failed to resolve dependencies (Set log level to 'warn' in BuildConfig.groovy for more information):
        • org.grails.plugins:tomcat:2.3.0

        (Use --stacktrace to see the full trace)

        Error Resolve error obtaining dependencies: Failed to resolve dependencies (Set log level to 'warn' in BuildConfig.groovy for more information):
        • org.grails.plugins:hibernate:2.3.0

        (Use --stacktrace to see the full trace)

        Error Resolve error obtaining dependencies: Failed to resolve dependencies (Set log level to 'warn' in BuildConfig.groovy for more information):
        • org.grails.plugins:hibernate:2.3.0

        (Use --stacktrace to see the full trace)

        Error Failed to resolve dependencies (Set log level to 'warn' in BuildConfig.groovy for more information):
        • org.grails.plugins:tomcat:2.3.0
        Run 'grails dependency-report' for further information.

        What I did wrong ?

        Show
        Martin Grigorov added a comment - Downloaded Grails 2.3.0. Unzipped it in ~/devel/grails-2.3.0. $ export PATH=$PATH:~/devel/grails-2.3.0/bin /tmp/grails-generator $ grails doc Configuring classpath Error Resolve error obtaining dependencies: Failed to resolve dependencies (Set log level to 'warn' in BuildConfig.groovy for more information): org.grails.plugins:tomcat:2.3.0 (Use --stacktrace to see the full trace) Error Resolve error obtaining dependencies: Failed to resolve dependencies (Set log level to 'warn' in BuildConfig.groovy for more information): org.grails.plugins:hibernate:2.3.0 (Use --stacktrace to see the full trace) Error Resolve error obtaining dependencies: Failed to resolve dependencies (Set log level to 'warn' in BuildConfig.groovy for more information): org.grails.plugins:hibernate:2.3.0 (Use --stacktrace to see the full trace) Error Failed to resolve dependencies (Set log level to 'warn' in BuildConfig.groovy for more information): org.grails.plugins:tomcat:2.3.0 Run 'grails dependency-report' for further information. What I did wrong ?
        Hide
        Martin Grigorov added a comment -

        I've created a new Grails app:
        $ grails create-app helloworld
        $ grailsw doc (Note the 'w' at the end!)
        this downloaded again grails-2.3.0 (120Mb) and again failed with the error above Let ask Google

        Show
        Martin Grigorov added a comment - I've created a new Grails app: $ grails create-app helloworld $ grailsw doc (Note the 'w' at the end!) this downloaded again grails-2.3.0 (120Mb) and again failed with the error above Let ask Google
        Hide
        Paul Bors added a comment -

        Hey Andrea Del Bene,

        Will the new version of the guide in the new format incorporate the fixes from the old project's home page?

        Show
        Paul Bors added a comment - Hey Andrea Del Bene , Will the new version of the guide in the new format incorporate the fixes from the old project's home page?
        Hide
        Martin Grigorov added a comment -

        http://www.jworks.nl/2013/09/11/upgrading-grails-2-2-4-to-2-3-0/ solved the issue with Tomcat. But Hibernate dependency still fails.
        I'll download 2.2.0

        Show
        Martin Grigorov added a comment - http://www.jworks.nl/2013/09/11/upgrading-grails-2-2-4-to-2-3-0/ solved the issue with Tomcat. But Hibernate dependency still fails. I'll download 2.2.0
        Hide
        Martin Grigorov added a comment -

        http://wicket.apache.org/guide/
        Almost works. Some CSS files are missing.

        Show
        Martin Grigorov added a comment - http://wicket.apache.org/guide/ Almost works. Some CSS files are missing.
        Hide
        Andrea Del Bene added a comment -

        Paul Bors yes of course. Unfortunately lately my spare time has greatly decreased and I didn't manage to incorporate your second part of the proof reading.
        Martin Grigorov I'm also using grails 2.2.0 under Ubuntu and I've install it using the instructions you find on the site: http://grails.org/download/ubuntu. Unfortunately I've found another problem when I try to generate the pdf, but to solve it I think we must change the document source. Here is the error:

        $ grails doc --pdf

        Built user manual at /home/andrea/git/wicket-userguide/grails-generator/../index.html
        [Fatal Error] :758:74: The element type "wicket:extend" must be terminated by the matching end-tag "</wicket:extend>".
        Error Error executing script Doc: org.xml.sax.SAXParseException; lineNumber: 758; columnNumber: 74; The element type "wicket:extend" must be terminated by the matching end-tag "</wicket:extend>". (Use --stacktrace to see the full trace)
        Show
        Andrea Del Bene added a comment - Paul Bors yes of course. Unfortunately lately my spare time has greatly decreased and I didn't manage to incorporate your second part of the proof reading. Martin Grigorov I'm also using grails 2.2.0 under Ubuntu and I've install it using the instructions you find on the site: http://grails.org/download/ubuntu . Unfortunately I've found another problem when I try to generate the pdf, but to solve it I think we must change the document source. Here is the error: $ grails doc --pdf Built user manual at /home/andrea/git/wicket-userguide/grails-generator/../index.html [Fatal Error] :758:74: The element type "wicket:extend" must be terminated by the matching end-tag "</wicket:extend>". Error Error executing script Doc: org.xml.sax.SAXParseException; lineNumber: 758; columnNumber: 74; The element type "wicket:extend" must be terminated by the matching end-tag "</wicket:extend>". (Use --stacktrace to see the full trace)
        Hide
        Martin Grigorov added a comment -

        Voila!
        It is there.

        Show
        Martin Grigorov added a comment - Voila! It is there.
        Hide
        Paul Bors added a comment -

        Can we have a tutorial on http://wicket.apache.org/guide/ about how to send push requests to that guide?

        Show
        Paul Bors added a comment - Can we have a tutorial on http://wicket.apache.org/guide/ about how to send push requests to that guide?
        Hide
        Martin Grigorov added a comment - - edited
        Show
        Martin Grigorov added a comment - - edited How to contribute - http://wicket.apache.org/guide/guide/chapter26.html
        Hide
        Martin Grigorov added a comment -

        There is a problem with this setup though.
        The shell scripts that run Jekyll (regenerate.sh and liveedit.sh) delete all files from _site folder, including the guide. They do this to be able to preserve .svn folders.

        Option 1) use Git for PubSub (.git/ is only in the root folder)
        Option 2) Use newer Subversion (.svn/ is only in the root folder)
        Option 3) ???

        Show
        Martin Grigorov added a comment - There is a problem with this setup though. The shell scripts that run Jekyll (regenerate.sh and liveedit.sh) delete all files from _site folder, including the guide. They do this to be able to preserve .svn folders. Option 1) use Git for PubSub (.git/ is only in the root folder) Option 2) Use newer Subversion (.svn/ is only in the root folder) Option 3) ???
        Hide
        Martijn Dashorst added a comment -

        I suggest using a newer svn. I have done so for the last 8 releases or so, and it works like a charm. With SVN > 1.8 there is just one .svn folder in the root, rendering the preservation step moot, and making it a lot faster as well.

        option 3: make regenerate "know about our guide", such that it will regenerate the guide as well. This will ensure that deleted files are actually removed (as long as wel "svn rm" them...)

        Show
        Martijn Dashorst added a comment - I suggest using a newer svn. I have done so for the last 8 releases or so, and it works like a charm. With SVN > 1.8 there is just one .svn folder in the root, rendering the preservation step moot, and making it a lot faster as well. option 3: make regenerate "know about our guide", such that it will regenerate the guide as well. This will ensure that deleted files are actually removed (as long as wel "svn rm" them...)
        Hide
        Paul Bors added a comment -

        Quick question about versioning this guide.
        What would happen when Wicket 7.x is released and there will be some API changes rendering the text in the guide off.

        Should then the guide's major version match that of Wicket's major version?
        ie: Instead of starting at v1 start at v6 since it's documenting Wicket 6.x?

        Then when Wicket 7.x will be release the guide can be branched and updated under v7 thus users will know which version of the guide to refer to for the Wicket version they use.

        Show
        Paul Bors added a comment - Quick question about versioning this guide. What would happen when Wicket 7.x is released and there will be some API changes rendering the text in the guide off. Should then the guide's major version match that of Wicket's major version? ie: Instead of starting at v1 start at v6 since it's documenting Wicket 6.x? Then when Wicket 7.x will be release the guide can be branched and updated under v7 thus users will know which version of the guide to refer to for the Wicket version they use.
        Hide
        Paul Bors added a comment -

        Also, can we have a "wicket-guide" component in Jira?

        Show
        Paul Bors added a comment - Also, can we have a "wicket-guide" component in Jira?
        Hide
        Martijn Dashorst added a comment -

        I've added a guide component to JIRA... Andrea is the component lead.

        Show
        Martijn Dashorst added a comment - I've added a guide component to JIRA... Andrea is the component lead.
        Hide
        Martijn Dashorst added a comment -

        Re: versioning

        I think it is better to inline the differences in the reference guide for different versions rather than branch it out. Most text is reusable and only some examples will become different. This way the reference guide can also function as a migration guide.

        On the other hand, a migration guide would be easier as one chapter.

        Basically I'd rather have us focus on one guide and make it high quality than on 3 versions of the guide and do a mediocre job of maintaining it.

        Show
        Martijn Dashorst added a comment - Re: versioning I think it is better to inline the differences in the reference guide for different versions rather than branch it out. Most text is reusable and only some examples will become different. This way the reference guide can also function as a migration guide. On the other hand, a migration guide would be easier as one chapter. Basically I'd rather have us focus on one guide and make it high quality than on 3 versions of the guide and do a mediocre job of maintaining it.
        Hide
        Paul Bors added a comment -

        Then having the guide against the latest version is fine as long as for each migration there is a chapter (or at least migrating from the last major version).

        My first migration was from a Wicket 1.3.x to 1.5.x and I had to read all migration wiki pages that I aggregated into a single doc and spread it out into different tasks that my team and I had to go through to migrate over the entire project. Wasn't a pleasant mini-project but we did it!

        I'm not sure if the migration doc really belongs in this guide because of 2 reasons I can think of:

        1. That chapter on migrating will keep growing over time
          What would happen with older migration guides?
        2. It would be harder for the community to add new sections to the migration as they run into them
          A wiki is easier to edit and contribute to that this guide that requires code to be checked out, create patches, push requests and etc.
        Show
        Paul Bors added a comment - Then having the guide against the latest version is fine as long as for each migration there is a chapter (or at least migrating from the last major version). My first migration was from a Wicket 1.3.x to 1.5.x and I had to read all migration wiki pages that I aggregated into a single doc and spread it out into different tasks that my team and I had to go through to migrate over the entire project. Wasn't a pleasant mini-project but we did it! I'm not sure if the migration doc really belongs in this guide because of 2 reasons I can think of: That chapter on migrating will keep growing over time What would happen with older migration guides? It would be harder for the community to add new sections to the migration as they run into them A wiki is easier to edit and contribute to that this guide that requires code to be checked out, create patches, push requests and etc.
        Hide
        Andrea Del Bene added a comment -

        Thank you for your work to put the guide online!

        About versioning: I think that it would be better to create branches/tags for different version as I also don't think that a migration guide should be part of the user guide.
        About setup: it would be grate if we could implement the third option proposed by Martijn.

        Show
        Andrea Del Bene added a comment - Thank you for your work to put the guide online! About versioning: I think that it would be better to create branches/tags for different version as I also don't think that a migration guide should be part of the user guide. About setup: it would be grate if we could implement the third option proposed by Martijn.
        Hide
        Andrea Del Bene added a comment -

        I did some work to allow the guide to be exported as pdf (the command is 'grails doc --pdf'). Most of the effort has been spent to resize pictures and code snippet to fit in the pdf format. I've kept the original pictures in a new folder locate in src/docs/imgOrigin.
        The next step will be to remove comSysto copyright and upper-left logo, replacing them with Apache Foundation name and logo. I'd like also to keep a reference to comSysto in the introduction, inserting something like 'first release by comSysto' after the original introduction.

        Show
        Andrea Del Bene added a comment - I did some work to allow the guide to be exported as pdf (the command is 'grails doc --pdf'). Most of the effort has been spent to resize pictures and code snippet to fit in the pdf format. I've kept the original pictures in a new folder locate in src/docs/imgOrigin. The next step will be to remove comSysto copyright and upper-left logo, replacing them with Apache Foundation name and logo. I'd like also to keep a reference to comSysto in the introduction, inserting something like 'first release by comSysto' after the original introduction.
        Hide
        Andrea Del Bene added a comment - - edited

        I've updated the documents and regenerated the html to display the Apache logo and copyright. Now it's "officially" part of Wicket.

        Show
        Andrea Del Bene added a comment - - edited I've updated the documents and regenerated the html to display the Apache logo and copyright. Now it's "officially" part of Wicket.
        Hide
        Martijn Dashorst added a comment -
        Show
        Martijn Dashorst added a comment - Would a 7.x branch work? i.e. http://wicket.apache.org/guide/7.x http://wicket.apache.org/guide/6.x ?
        Hide
        Martijn Dashorst added a comment -

        We should probably look at the site structure and separate out the guide such that svnpubsub can deploy them separately, and make it a better experience to maintain the website separately from the guide and vice versa.

        Show
        Martijn Dashorst added a comment - We should probably look at the site structure and separate out the guide such that svnpubsub can deploy them separately, and make it a better experience to maintain the website separately from the guide and vice versa.
        Hide
        Andrea Del Bene added a comment -

        I'm a little bit out from technical details about the site, but what folder/structure do you suggest to use to store the guide?

        Show
        Andrea Del Bene added a comment - I'm a little bit out from technical details about the site, but what folder/structure do you suggest to use to store the guide?
        Hide
        Martin Grigorov added a comment -

        Closing the ticket because the guide is incorporated in the site.
        When we start upgrade/update of the guide for things specific to Wicket 7 we will open a new ticket.

        Show
        Martin Grigorov added a comment - Closing the ticket because the guide is incorporated in the site. When we start upgrade/update of the guide for things specific to Wicket 7 we will open a new ticket.

          People

          • Assignee:
            Andrea Del Bene
            Reporter:
            Martijn Dashorst
          • Votes:
            0 Vote for this issue
            Watchers:
            5 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development