You are viewing a plain text version of this content. The canonical link for it is here.
Posted to torque-dev@db.apache.org by tf...@apache.org on 2010/02/23 19:29:40 UTC
svn commit: r915469 -
/db/torque/torque4/trunk/torque-site/src/site/xdoc/developer-info/site-edit-deploy.xml
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