db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r915469 - /db/torque/torque4/trunk/torque-site/src/site/xdoc/developer-info/site-edit-deploy.xml
Date Tue, 23 Feb 2010 18:29:40 GMT
Author: tfischer
Date: Tue Feb 23 18:29:40 2010
New Revision: 915469

URL: http://svn.apache.org/viewvc?rev=915469&view=rev
Log:
update info on how to build the site

Modified:
    db/torque/torque4/trunk/torque-site/src/site/xdoc/developer-info/site-edit-deploy.xml

Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/developer-info/site-edit-deploy.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/developer-info/site-edit-deploy.xml?rev=915469&r1=915468&r2=915469&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/developer-info/site-edit-deploy.xml
(original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/developer-info/site-edit-deploy.xml
Tue Feb 23 18:29:40 2010
@@ -21,7 +21,6 @@
 <document>
   <properties>
     <title>Editing and Deploying the Torque site</title>
-    <author email="fischer@seitenbau.de">Thomas Fischer</author>
   </properties>
 
   <body>
@@ -34,154 +33,88 @@
      </p>
    </section>
    
-   <section name="Organisation of the site's source code">
+   <section name="Site source code and build process">
      <p>
-       The Torque site consists of a "frame site" and the "sites" of the 
-       various components of Torque (== maven subprojects).  
-       The sites of the components are embedded
-       in the main site (i.e. the user does not see that he has entered 
-       the component's site, as the navigation on the left hand side 
-       looks the same).  In contrast to the subprojects, the "frame site" 
-       has no tags and branches in svn. (This is why you cannot get
-       the frame site from the trunks svn directory).
-     </p>
-     
-     <p>
-       Each subproject keeps its documentation in its own xdocs subdirectory.
-       Currently, the templates subproject does not have its own documentation.
-       There is also a subproject (docs-all-components) which contains
-       documentation which affects mor than one subproject. 
-     </p>
-   </section>
-   
-   <section name="Adding new documentation">
-     <p>
-       If you want to add new documents, please think about where 
-       they should be added:
-       
+       The complete Torque site resides in the module torque-site.
+       Only the reports from the subprojects are pulled into the main
+       site via a process documented below.
+       The subprojects do not have an own xdoc subdirectory.
+     </p>
+     <subsection name="Transferring the module reports to the main site">
+       <p>
+         The project reports of the subprojects are pulled into the
+         main site during the site lifecycle of the main site. 
+         This happens in the following steps, which are defined
+         in the pom.xml of the torque-site module:
+       </p>
        <ul>
          <li>
-           If they affect only one component of Torque, add them to the xdocs
-           of the component.
+           In the pre-site phase, the reports are copied from the
+           site directories of the respective modules to the target directory
+           of the site module 
+           (directories generator-site, runtime-site, ...).
+           They are renamed to xml, the doctype header
+           is removed, and in some cases xhtml errors are fixed.
+         </li>  
+         <li>
+           In the site phase, the copied reports are tarnsformed by the xslt
+           stylesheet torque-site/src/site/xslt/body-content.xsl
+           such that only the body part remains and the "page frame"
+           is omitted. The result is written to the directories
+           generator-site-content, runtime-site-content...
+         </li>
+         <li>
+           In the post-site phase, the body parts of the report are
+           inserted into the placeholder pages which sources can be found in
+           torque-site/src/site/xdoc/documentation/modules/generator/reports,
+           torque-site/src/site/xdoc/documentation/modules/runtime/reports...
+           Some reports do not need to be transformed, e.g. the
+           cobertura report, the javadocs and the sources xref, they are copied
+           unchanged.
          </li>
-         <li>
-           If the new documents affect Torque as a whole, add them to the
-           site subproject.
-         </li>
-       </ul>
-     </p>
-   </section>
-   
-   <section name="Editing the navigation">
-     <p>
-       As the navigation should look "the same" from the main site and
-       each subproject, changes made to the "frame navigation", i.e. the
-       navigation items which can be seen from every page of the site,
-       must be made in the site subproject and the site of every component
-       alike. 
-       (Probably there is some way to script this, but as this will probably
-       be very different for a Maven 2 build, I do not think it is worth while
-       now.)
-     </p>
-     
-     <p>
-       If the change in the navigation affects a place which can not be seen
-       from everywhere in the project (e.g. a new item in the "references"
-       section of the runtime docs), there is no need to update the 
-       navigation.xml's of the other subprojects and the frame site.
-     </p>
+      </ul>
+     </subsection>
    </section>
    
    <section name="Deploying the site">
      <p>
        This is a step-by-step guide to deploy the whole site. 
-       If you only want to deploy the documentation for a subproject,
-       omit the steps to be omitted from the description below.
        The guide assumes that the necessary ssh properties and maven properties
        are set.
-       <ul>
-         <li>
-           It might be a good idea to create a tar.gz backup of the current
-           state of the site in your home directory, in case anything goes
-           wrong.
-         </li>
-         <li>
-           Build the sites of the frame site and the components using
-           "maven site" in each project.  This might take a while because of
-           the linkchecking.
-         </li>
-         <li>
-           Deploy the frame site and the components using "maven site:deploy".
-           The frame site will be deployed to the correct place.  The sites
-           of the subprojects will be deployed to 
-           db.apache.org/torque/${subproject-name}, where they are not visible.
-         </li>
-         <li>
-           Move the sites of the subprojects to the correct place, 
-           db.apache.org/torque/releases/torque-${version}/${subproject-name}.
-           (Probably this step can be automated by changing the siteDirectory
-           in the pom, I have not tested this.)
-         </li>
-         <li>
-           Empty the cache of your browser and check everything is ok on
-           <a href="http://db.apache.org/torque/">http://db.apache.org/torque/</a>
-         </li>
-         <li>
-           If you are satisfied with the new site and noone complains during
-           the next few days, delete the backup tar.gz.
-         </li>
-       </ul>
      </p>
+     <ul>
+       <li>
+         It might be a good idea to create a tar.gz backup of the current
+         state of the site in your home directory, in case anything goes
+         wrong.
+       </li>
+       <li>
+         run "mvn install" in the torque-parent module.
+       </li>
+       <li>
+         run "mvn post-site" in the torque-parent module.
+       </li>
+       <li>
+         check the site in /torque-site/target/site
+       </li>
+       <li>
+         ATTENTION: I tried this in the new build!<br/>
+         run mvn site:deploy in the torque-site module.
+       </li>
+       <li>
+         Empty the cache of your browser and check everything is ok on
+         <a href="http://db.apache.org/torque/">http://db.apache.org/torque/</a>
+       </li>
+       <li>
+         If you are satisfied with the new site and no-one complains during
+         the next few days, delete the backup tar.gz.
+       </li>
+     </ul>
    </section>
    
    <section name="Updating the site for a new release">
      <p>
-       The following steps are necessary if a new release is created.
-       I have not tested the procedure, so think yourself instead of following
-       blindly (as always :-) )
-       
-       <ul>
-         <li>
-           Create a backup tar.gz of the site AND copy the whole site 
-           to your apache home directory for the site archive.
-         </li>
-         <li>
-           In the _COPY_ of the site for the archive, remove the previous
-           versions in the releases/ subdirectory.  E.g. if the current version
-           is Torque 3.3 and you want to create the site for the release of 
-           Torque 4.0, remove everything except the torque-3.3 subdirectory
-           of the releases directory.
-         </li>
-         <li>
-           Add the old version to the "Previous Releases" section in the
-           navigation.xml of the frame site.  Also, change the release number
-           in all navigation.xml's to the new current release number.
-         </li>
-         <li>
-           Deploy the whole site (see above).
-         </li>
-         <li>
-           Clean the directory of the previous version in the new version of
-           the site (NOT in the copy) (in the above examples, this would be 
-           removing releases/torque-3.3/runtime, releases/torque-3.3/generator
-           and so on.)
-         </li>
-         <li>
-           Now copy the copy of the old site to the freshly cleaned subdirectory
-           of the releases/ directory.  The idea is that the "old"
-           http://db.apache.org/torque.index.html is now available under
-           http://db.apache.org/torque/releases/${old.version}/index.html,
-           and so on.
-         </li>
-         <li>
-           Remove the old dev version (if it exists) from the releases 
-           subdirectoy (in our above eample, this would be 
-           releases/torque-3.3-dev).
-         </li>
-         <li>
-           Empty your browser cache and check the results.
-         </li>
-       </ul>
+       TODO
      </p>
    </section>
 



---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org


Mime
View raw message