Hi Folks, Synapse binary distribution ships with some documentation (the docs directory). In the previous releases, our build system was configured to simply rename some of the Xdoc files into html files and include them in the docs directory. In the new documentation, we have used the proper Xdoc syntax to arrange and format the content. Therefore simply renaming the Xdoc files to have a .html extension does not work anymore. Browsers do not properly render the content.
So now we need to run the maven site plugin on the Xdoc files before the distribution module is built. The output of the plugin should be packed into the docs directory of the binary distribution. In the 2.1 branch we made a few changes to get this working. 1. Included the maven site plugin in the build configuration of the root pom and configured it to run in the install phase (this causes the site plugin to run when executing 'mvn clean install') 2. The above change caused the API docs to get built too (before any of the modules are built). And that had a serious impact on the build order of the modules and we experienced many build breaks. So we removed the javadoc plugin from the reporting configuration of the root pom and included that too in the build configuration. With these changes in place we now have the desired behavior. Properly formatted and structured HTML content is packaged into the binary distribution and war distribution of Synapse. However we need to run 'mvn javadoc:javadoc' separately to build the API docs. Running 'mvn site:site' will not build the API docs anymore. I guess this is a very reasonable solution at the moment. However looking into the future, is there a better way to solve this problem? Couple of alternatives I can think of: a. Not shipping the documentation with the binary distribution b. Adding an ANT task to the distribution module pom to run mvn site:site at the root level WDYT? Thanks -- Hiranya Jayathilaka Associate Technical Lead; WSO2 Inc.; http://wso2.org E-mail: [email protected]; Mobile: +94 77 633 3491 Blog: http://techfeast-hiranya.blogspot.com
