Repository: incubator-trafodion Updated Branches: refs/heads/master 53d586bca -> accb00a6a
[TRAFODION-1776] Reduce web-site build steps Added child modules to top-level POM file to build each document. Must use "mvn post-site" command, so that all docs get copied into website docs directory. Updated documentation on building docs and website. Updated documents (except for install_guide, since it is still in development) to use the current Trafodion release version. This requires sourcing the env.sh file before building docs. Project: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/commit/e5b4ea68 Tree: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/tree/e5b4ea68 Diff: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/diff/e5b4ea68 Branch: refs/heads/master Commit: e5b4ea68cf16d663f6d476a6153b1d12c7ad044d Parents: ff4b7dd Author: Steve Varnau <[email protected]> Authored: Fri Jan 22 23:48:48 2016 +0000 Committer: Steve Varnau <[email protected]> Committed: Sat Jan 23 00:11:17 2016 +0000 ---------------------------------------------------------------------- core/rest/pom.xml | 41 +++++++++++++++- dcs/pom.xml | 40 +++++++++++++++- docs/.gitignore | 1 + docs/client_install/pom.xml | 10 +++- docs/command_interface/pom.xml | 9 +++- docs/install_guide/pom.xml | 7 +++ docs/odb_user/pom.xml | 9 +++- docs/sql_reference/pom.xml | 9 +++- docs/src/site/markdown/document.md | 84 +++++++-------------------------- docs/src/site/markdown/website.md | 12 ++--- pom.xml | 11 +++++ 11 files changed, 153 insertions(+), 80 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/core/rest/pom.xml ---------------------------------------------------------------------- diff --git a/core/rest/pom.xml b/core/rest/pom.xml index 47216cb..e7f2505 100644 --- a/core/rest/pom.xml +++ b/core/rest/pom.xml @@ -34,7 +34,7 @@ <artifactId>rest</artifactId> <packaging>jar</packaging> <version>${env.TRAFODION_VER}</version> - <name>rest</name> + <name>Trafodion REST</name> <url>http://wiki.trafodion.org</url> <developers> @@ -320,7 +320,46 @@ </execution> </executions> </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-antrun-plugin</artifactId> + <version>1.8</version> + <inherited>false</inherited> + <executions> + <execution> + <id>populate-release-directories</id> + <phase>post-site</phase> + <configuration> + <target name="Populate Release Directories"> + <!-- The website uses the following organization for the docs/target/docs directory: + - To ensure a known location, the base directory contains the LATEST version of the web book and the PDF files. + - The know location is docs/target/docs/<document> + - target/docs/<version>/<document> contains version-specific renderings of the documents. + - target/docs/<version>/<document> contains the PDF version and the web book. The web book is named index.html + --> + <!-- Copy the PDF file to its target directories --> + <!-- None for REST --> + <!-- Copy the Web Book files to their target directories --> + <copy todir="${basedir}/../../docs/target/docs/rest_reference"> + <fileset dir="${basedir}/target/site"> + <include name="**/*.*"/> <!--All sub-directories, too--> + </fileset> + </copy> + <copy todir="${basedir}/../../docs/target/docs/${project.version}/rest_reference"> + <fileset dir="${basedir}/target/site"> + <include name="**/*.*"/> <!--All sub-directories, too--> + </fileset> + </copy> + </target> + </configuration> + <goals> + <goal>run</goal> + </goals> + </execution> + </executions> + </plugin> </plugins> + <pluginManagement> <plugins> <!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.--> http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/dcs/pom.xml ---------------------------------------------------------------------- diff --git a/dcs/pom.xml b/dcs/pom.xml index 4e9725f..284420b 100644 --- a/dcs/pom.xml +++ b/dcs/pom.xml @@ -35,7 +35,7 @@ <artifactId>dcs</artifactId> <packaging>jar</packaging> <version>${env.TRAFODION_VER}</version> - <name>dcs</name> + <name>Trafodion Database Connectivity Services</name> <url>http://wiki.trafodion.org</url> <developers> @@ -450,6 +450,44 @@ </execution> </executions> </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-antrun-plugin</artifactId> + <version>1.8</version> + <inherited>false</inherited> + <executions> + <execution> + <id>populate-release-directories</id> + <phase>post-site</phase> + <configuration> + <target name="Populate Release Directories"> + <!-- The website uses the following organization for the docs/target/docs directory: + - To ensure a known location, the base directory contains the LATEST version of the w + - The know location is docs/target/docs/<document> + - target/docs/<version>/<document> contains version-specific renderings of the documents. + - target/docs/<version>/<document> contains the PDF version and the web book. The web book is named index. + --> + <!-- Copy the PDF file to its target directories --> + <!-- None for DCS --> + <!-- Copy the Web Book files to their target directories --> + <copy todir="${basedir}/../docs/target/docs/dcs_reference"> + <fileset dir="${basedir}/target/site"> + <include name="**/*.*"/> <!--All sub-directories, too--> + </fileset> + </copy> + <copy todir="${basedir}/../docs/target/docs/${project.version}/dcs_reference"> + <fileset dir="${basedir}/target/site"> + <include name="**/*.*"/> <!--All sub-directories, too--> + </fileset> + </copy> + </target> + </configuration> + <goals> + <goal>run</goal> + </goals> + </execution> + </executions> + </plugin> </plugins> </build> http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/docs/.gitignore ---------------------------------------------------------------------- diff --git a/docs/.gitignore b/docs/.gitignore index b83d222..56256e4 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ /target/ +/*/target/ http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/docs/client_install/pom.xml ---------------------------------------------------------------------- diff --git a/docs/client_install/pom.xml b/docs/client_install/pom.xml index d27c65b..a446ee0 100644 --- a/docs/client_install/pom.xml +++ b/docs/client_install/pom.xml @@ -26,13 +26,21 @@ <modelVersion>4.0.0</modelVersion> <groupId>org.apache.trafodion</groupId> <artifactId>client-install-guide</artifactId> - <version>1.3.0</version> + <version>${env.TRAFODION_VER}</version> <packaging>pom</packaging> <name>Trafodion Client Installation Guide</name> <description>This guide describes how to install different Trafodion client applications.</description> <url>http://trafodion.incubator.apache.org</url> <inceptionYear>2015</inceptionYear> + <parent> + <groupId>org.apache.trafodion</groupId> + <artifactId>trafodion</artifactId> + <version>1.3.0</version> + <relativePath>../../pom.xml</relativePath> + </parent> + + <licenses> <license> <name>The Apache Software License, Version 2.0</name> http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/docs/command_interface/pom.xml ---------------------------------------------------------------------- diff --git a/docs/command_interface/pom.xml b/docs/command_interface/pom.xml index 1c92205..d342cb0 100644 --- a/docs/command_interface/pom.xml +++ b/docs/command_interface/pom.xml @@ -26,12 +26,19 @@ <modelVersion>4.0.0</modelVersion> <groupId>org.apache.trafodion</groupId> <artifactId>command-interface-guide</artifactId> - <version>1.3.0</version> + <version>${env.TRAFODION_VER}</version> <packaging>pom</packaging> <name>Trafodion Command Interface Guide</name> <description>This guide describes how to use the Trafodion Command Interface (TrafCI).</description> <url>http://trafodion.incubator.apache.org</url> <inceptionYear>2015</inceptionYear> + <parent> + <groupId>org.apache.trafodion</groupId> + <artifactId>trafodion</artifactId> + <version>1.3.0</version> + <relativePath>../../pom.xml</relativePath> + </parent> + <licenses> <license> http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/docs/install_guide/pom.xml ---------------------------------------------------------------------- diff --git a/docs/install_guide/pom.xml b/docs/install_guide/pom.xml index 46a0658..d4fa908 100644 --- a/docs/install_guide/pom.xml +++ b/docs/install_guide/pom.xml @@ -32,6 +32,13 @@ <description>This guide describes how to install Trafodion.</description> <url>http://trafodion.incubator.apache.org</url> <inceptionYear>2015</inceptionYear> + <parent> + <groupId>org.apache.trafodion</groupId> + <artifactId>trafodion</artifactId> + <version>1.3.0</version> + <relativePath>../../pom.xml</relativePath> + </parent> + <licenses> <license> http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/docs/odb_user/pom.xml ---------------------------------------------------------------------- diff --git a/docs/odb_user/pom.xml b/docs/odb_user/pom.xml index d76fb69..8df0c7c 100644 --- a/docs/odb_user/pom.xml +++ b/docs/odb_user/pom.xml @@ -26,12 +26,19 @@ <modelVersion>4.0.0</modelVersion> <groupId>org.apache.trafodion</groupId> <artifactId>odb-user-guide</artifactId> - <version>1.3.0</version> + <version>${env.TRAFODION_VER}</version> <packaging>pom</packaging> <name>Trafodion odb User Guide</name> <description>This guide describes how to odb, a multi-threaded, ODBC-based command-line tool, to perform various operations on a Trafodion database.</description> <url>http://trafodion.incubator.apache.org</url> <inceptionYear>2015</inceptionYear> + <parent> + <groupId>org.apache.trafodion</groupId> + <artifactId>trafodion</artifactId> + <version>1.3.0</version> + <relativePath>../../pom.xml</relativePath> + </parent> + <licenses> <license> http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/docs/sql_reference/pom.xml ---------------------------------------------------------------------- diff --git a/docs/sql_reference/pom.xml b/docs/sql_reference/pom.xml index ee6282f..bae476d 100644 --- a/docs/sql_reference/pom.xml +++ b/docs/sql_reference/pom.xml @@ -26,7 +26,7 @@ <modelVersion>4.0.0</modelVersion> <groupId>org.apache.trafodion</groupId> <artifactId>sq-reference-manual</artifactId> - <version>1.3.0</version> + <version>${env.TRAFODION_VER}</version> <packaging>pom</packaging> <name>Trafodion SQL Reference Manual</name> <description>This manual describes reference information about the syntax of SQL statements, @@ -35,6 +35,13 @@ </description> <url>http://trafodion.incubator.apache.org</url> <inceptionYear>2015</inceptionYear> + <parent> + <groupId>org.apache.trafodion</groupId> + <artifactId>trafodion</artifactId> + <version>1.3.0</version> + <relativePath>../../pom.xml</relativePath> + </parent> + <licenses> <license> http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/docs/src/site/markdown/document.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/document.md b/docs/src/site/markdown/document.md index 09bccf1..fe400cb 100644 --- a/docs/src/site/markdown/document.md +++ b/docs/src/site/markdown/document.md @@ -66,27 +66,29 @@ Please refer to the following web sites for guidance for information about worki * [AsciiDoc User Guide](http://www.methods.co.nz/asciidoc/chunked/index.html) * [AsciiDoc cheatsheet](http://powerman.name/doc/asciidoc) -Once you've made the desired changes, then do the following: +Once you have made the desired changes, then do the following: -## DCS and REST +## Building an Individual Document -1. Build the document using **```mvn clean site```** against the directory containing the document; for example: **```dcs```** or **```core/rest```**. -2. Verify the content in the generated **```target```** directory. The **```target/index.html```** file provides the entry point for the web book; the **```target/apidocs/index.html```** file contains the entry point for API documentation. +1. Be sure to source env.sh, so that the TRAFODION_VER environment variable is defined. +2. Build the document using **```mvn clean site```** in the directory containing the document; for example: **```dcs```** or **```docs/odb_user```**. +3. Verify the content in the generated **```target```** directory. + * The **```target/index.html```** file provides the entry point for the web book. + * For those that have API documentation, the **```target/apidocs/index.html```** file contains the entry point. + * For those that have PDF, the **```target/index.pdf```** file contains the PDF version of the document. -## Other Documents +## Building the Entire Website, including Documents -1. Build the document using **```mvn clean site```** against the directory containing the document; for example: **```docs/client_install```** or **```docs/odb_user```**. -2. Verify the content in the generated **```target```** directory. The **```target/index.pdf```** file contains the PDF version of the document while -**```target/site/index.html```** contains the web-book version of the document. +1. Be sure to source env.sh, so that the TRAFODION_VER environment variable is defined. +2. Build everything using **```mvn clean post-site```** in the top-level directory. +3. Verify the contents in the generated **```docs/target```** directory. + * All documents are in **```docs/target/docs```** directory. # Build Trafodion Document Tree The external version of the Trafodion Document Tree is published to http://trafodion.incubator.apache.org/docs. Please refer to [Publish](#publish) below. The build version of the Trafodion Document Tree is located in **```docs/target/docs```**, which is created when you build the Trafodion web site in Maven. -<table><tr><td><strong>NOTE</strong><br />Build the web site <strong>before</strong> you use the <strong><code>post-site</code></strong> phase to copy in the document files. -If you don't, then the web-site build will wipe out the Trafodion Document Tree.</td></tr></table> - ## Version Directories The Trafodion Document Tree consists of **Version Directories**: @@ -98,8 +100,7 @@ Version Directory | Content * **```latest```**: Provides a well-known place for each document. This practice makes it possible to link to a document in instructional text, web sites, and other documents. -* **```<version>```**: Provides per-release versions of documents. Previous versions are kept in the web site's SVN repository ensuring that N versions of the documentation -are available. +* **```<version>```**: Provides per-release versions of documents. Previous versions are kept in the web site's git repository ensuring that previous versions of the documentation are available. ## Document Directories Each document is placed in its own **Document Directory**: @@ -127,66 +128,13 @@ File/Directory | Content The Document Directories are copied under the Version Directories thereby creating the web-accessible Trafodion document tree. -## Populate Trafodion Documentation Tree -The build version of the Trafodion Document Tree is populated as follows: - -<table> - <tr> - <th>Document</th> - <th>Instructions</th> - </tr> - <tr> - <td><strong>Client Installation Guide</strong></td> - <td>Run maven <strong><code>post-site</code></strong> build step.</td> - </tr> - <tr> - <td><strong>DCS Reference Guide Guide</strong></td> - <td> - <ol> - <li>Create Version Directories, if needed.</li> - <li>Create Document Directories, if needed.</li> - <li>Copy <strong><code>$SQ_HOME/dcs/target/site/</code></strong> to the appropriate Document Directories.</li> - </ol> - </td> - </tr> - <tr> - <td><strong>odb User Guide</strong></td> - <td>Run maven <strong><code>post-site</code></strong> build step.</td> - </tr> - <tr> - <td><strong>odb User Guide</strong></td> - <td>Run maven <strong><code>post-site</code></strong> build step.</td> - </tr> - <tr> - <td><strong>REST Reference Guide Guide</strong></td> - <td> - <ol> - <li>Create Version Directories, if needed.</li> - <li>Create Document Directories, if needed.</li> - <li>Copy <strong><code>$SQ_HOME/core/rest/target/site/</code></strong> to the appropriate Document Directories.</li> - </ol> - </td> - </tr> - <tr> - <td><strong>SQL Reference Guide Guide</strong></td> - <td>Run maven <strong><code>post-site</code></strong> build step.</td> - </tr> -</table> - - # Publish <div class="alert alert-dismissible alert-info"> <button type="button" class="close" data-dismiss="alert">&close;</button> - <p style="color:black">Publication is done when a committer is ready to update the external web site. You do <strong>not</strong> perform these steps as part of checking in changes.</p></div> - -Do the following: - -1. Build the web site. -2. Build the different document as described in [Making Changes](#making_changes) above. -3. Build the Trafodion Document Tree as described in [Build Trafodion Document Tree](#build_trafodion_document_tree) above. + <p style="color:black">Publication is done when a committer is ready to update the external web site. You do <strong>not</strong> publish as part of checking in changes.</p></div> -The resulting **```docs/target/docs/```** directory is checked into the web-site SVN branch. +Refer to [Website Publishing](website.html#publishing) for how the website and documents get published. http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/docs/src/site/markdown/website.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/website.md b/docs/src/site/markdown/website.md index ba60ef4..ac38ec7 100644 --- a/docs/src/site/markdown/website.md +++ b/docs/src/site/markdown/website.md @@ -97,12 +97,12 @@ Generates: Do the following: -1. Wait for the changes to be committed to the Trafodion master branch. -2. Build Trafodion site (mvn site). -3. If there are documentation changes: Follow the [documentation publishing](document.html#Publishing) instructions. -3. ```git clone``` https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git -4. Copy content of ```docs/target``` into the incubator-trafodion-site directory. Commit changes. -5. Push them back to the apache origin repo to the ```asf-site``` branch. +1. Fetch changes to be published from the Trafodion master branch. +2. Build Trafodion site (source ./env.sh; mvn post-site). +3. If there are documentation changes to prior releases, check out those release branch(es) and re-build the affected docs (mvn post-site). +4. ```git clone``` https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git +5. Copy content of ```docs/target``` into the incubator-trafodion-site directory. Commit changes. +6. Push them back to the apache origin repo to the ```asf-site``` branch. Once pushed, Apache gitpubsub takes care of populating http://incubator.trafodion.apache.org with your new changes. If they don't show up, pushing another empty (or whitespace change) commit may work to trigger the automation. http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/e5b4ea68/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index d1720b6..d065558 100644 --- a/pom.xml +++ b/pom.xml @@ -131,6 +131,16 @@ <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> </properties> + <modules> + <module>docs/client_install</module> + <module>dcs</module> + <module>core/rest</module> + <module>docs/command_interface</module> + <module>docs/install_guide</module> + <module>docs/odb_user</module> + <module>docs/sql_reference</module> + </modules> + <build> <resources> <resource> @@ -138,6 +148,7 @@ <filtering>true</filtering> </resource> </resources> + <outputDirectory>${basedir}/docs/target</outputDirectory> <pluginManagement> <plugins> <plugin>
