From f4f01971741bcd10cf6f48526406da0a55577ed4 Mon Sep 17 00:00:00 2001
From: Andrew Bayer <abayer@apache.org>
Date: Fri, 22 Jul 2011 20:04:15 +0000
Subject: [PATCH] SQOOP-78. Consolidate web-based documentation and tarball
 documentation.

Eliminates "webdocs" target from build, merged with "docs" target.
Web-based format for document delivery is used for local documentation as well.
Links to release notes, API documentation added to documentation homepage.
Release notes are generated for non-SNAPSHOT builds as part of "package" step.

From: Aaron Kimball <aaron@cloudera.com>

git-svn-id: https://svn.apache.org/repos/asf/incubator/sqoop/trunk@1149971 13f79535-47bb-0310-9956-ffa450edef68
---
 build.xml              | 49 +++++++++++++++++-------------------------
 src/docs/Makefile      | 41 +++++++++++++++++++++++------------
 src/docs/web/index.txt |  2 ++
 3 files changed, 49 insertions(+), 43 deletions(-)

diff --git a/build.xml b/build.xml
index d7a7311c..5ccf7978 100644
--- a/build.xml
+++ b/build.xml
@@ -97,8 +97,6 @@
   <property name="tar.file" location="${build.dir}/${artifact.name}.tar.gz" />
   <property name="build.docs.timestamp"
       location="${build.dir}/docs.timestamp" />
-  <property name="build.webdocs.timestamp"
-      location="${build.dir}/webdocs.timestamp" />
 
   <!-- compilation -->
   <property name="javac.deprecation" value="off"/>
@@ -450,7 +448,7 @@
   </target>
 
   <target name="package"
-      depends="jar-all,compile-all,docs,javadoc,ivy-retrieve-redist,scripts"
+      depends="jar-all,compile-all,docs,ivy-retrieve-redist,scripts"
       description="Create a redistributable package">
 
     <mkdir dir="${dist.dir}"/>
@@ -511,6 +509,8 @@
     <copy todir="${dist.dir}/docs" includeEmptyDirs="false" flatten="false">
       <fileset dir="${build.dir}/docs">
         <include name="**/*.html" />
+        <include name="**/*.css" />
+        <include name="images/**" />
       </fileset>
     </copy>
     <copy todir="${dist.dir}/docs/man" includeEmptyDirs="false" flatten="false">
@@ -716,15 +716,6 @@
     </uptodate>
   </target>
 
-  <target name="webdocs-uptodate" depends="init">
-    <uptodate property="webdocs.uptodate">
-      <srcfiles dir="${basedir}/src/docs/">
-        <include name="**/*.txt" />
-      </srcfiles>
-      <mapper type="merge" to="${build.webdocs.timestamp}" />
-    </uptodate>
-  </target>
-
   <target name="checkversion">
     <if>
       <contains string="${version}" substring="SNAPSHOT" />
@@ -737,6 +728,14 @@
   <target name="relnotes-uptodate" depends="init">
     <!-- releasenotes are considered up-to-date if they exist. -->
     <available property="relnotes.exists" file="${relnotes.filename}" />
+
+    <!-- if we're building a snapshot release, don't make release notes. -->
+    <if>
+      <contains string="${version}" substring="SNAPSHOT" />
+      <then>
+        <property name="relnotes.exists" value="true" />
+      </then>
+    </if>
   </target>
 
   <target name="relnotes" depends="relnotes-uptodate" unless="relnotes.exists"
@@ -751,11 +750,11 @@
     </exec>
   </target>
 
-  <target name="release" depends="checkversion,tar,webdocs,relnotes,releaseaudit"
+  <target name="release" depends="checkversion,tar,releaseaudit"
       description="Roll a release artifact">
     <echo message="Release complete" />
     <echo message="Binary tar: ${tar.file}" />
-    <echo message="Web docs: ${build.dir}/webdocs" />
+    <echo message="Documentation: ${build.dir}/docs" />
     <echo message="Release notes: ${relnotes.filename}" />
     <echo message="Release audit report: ${build.dir}/rat.log" />
   </target>
@@ -901,20 +900,10 @@
     </artifact:deploy>
   </target>
 
-  <target name="webdocs" depends="webdocs-uptodate" unless="webdocs.uptodate"
-      description="Build website documentation">
-    <exec executable="make" failonerror="true">
-      <arg value="-C" />
-      <arg value="${basedir}/src/docs" />
-      <arg value="BUILDROOT=${build.dir}" />
-      <arg value="VERSION=${version}" />
-      <arg value="website" />
-    </exec>
-    <touch file="${build.webdocs.timestamp}" />
-  </target>
+  <target name="docs" depends="real-docs,relnotes,javadoc"
+      description="Build documentation"/>
 
-  <target name="docs" depends="docs-uptodate" unless="docs.uptodate"
-      description="Build documentation">
+  <target name="real-docs" depends="docs-uptodate,init" unless="docs.uptodate">
     <exec executable="make" failonerror="true">
       <arg value="-C" />
       <arg value="${basedir}/src/docs" />
@@ -941,7 +930,7 @@
       <arg value="+%Y" />
     </exec>
     <javadoc
-      packagenames="com.cloudera.sqoop.*"
+      packagenames="com.cloudera.sqoop.lib.*"
       destdir="${build.javadoc}"
       author="true"
       version="true"
@@ -949,7 +938,9 @@
       windowtitle="${Name} ${version} API"
       doctitle="${Name} ${version} API"
       bottom="Copyright &amp;copy; ${year} Cloudera, Inc.">
-      <packageset dir="${src.dir}" />
+      <packageset dir="${src.dir}">
+        <include name="com/cloudera/sqoop/lib/**" />
+      </packageset>
       <classpath>
         <path refid="compile.classpath" />
       </classpath>
diff --git a/src/docs/Makefile b/src/docs/Makefile
index a84bce8b..f35a1914 100644
--- a/src/docs/Makefile
+++ b/src/docs/Makefile
@@ -15,16 +15,17 @@
 
 BUILDROOT=../../build
 BUILD_DIR=$(BUILDROOT)/docs
-WEBSITE_DIR=$(BUILDROOT)/webdocs
 
 VERSION=Unknown
 
-all: man userguide devguide
+all: man userguide devguide supportfiles index
 
 userguide: $(BUILD_DIR)/SqoopUserGuide.html
 
 devguide: $(BUILD_DIR)/SqoopDevGuide.html
 
+index: $(BUILD_DIR)/index.html
+
 MANSOURCES=$(shell echo man/sqoop*.txt)
 MANPAGES=$(MANSOURCES:.txt=.1.gz)
 
@@ -47,9 +48,6 @@ website:
 	xmlto -o $(WEBSITE_DIR) -m web/html.xsl html-nochunks web/index.xml
 	cp web/docbook.css $(WEBSITE_DIR)
 	rsync -a web/images $(WEBSITE_DIR)/
-	rm user/SqoopUserGuide.xml
-	rm dev/SqoopDevGuide.xml
-	rm web/index.xml
 
 man: $(MANPAGES)
 
@@ -62,18 +60,33 @@ man: $(MANPAGES)
 	mv $@ $(BUILD_DIR)
 
 $(BUILD_DIR)/SqoopUserGuide.html: user/*.txt
-	asciidoc -a toc -a toclevels=1 -a "toc-title=Table of Contents" \
-		-a revnumber=$(VERSION) -a "revdate=$(REVDATE)" \
-		user/SqoopUserGuide.txt
 	mkdir -p $(BUILD_DIR)
-	mv user/SqoopUserGuide.html $(BUILD_DIR)
+	asciidoc --unsafe -a revnumber=$(VERSION) \
+		-b docbook \
+		user/SqoopUserGuide.txt
+	xmlto -o $(BUILD_DIR) -m web/html.xsl html-nochunks user/SqoopUserGuide.xml
+	rm user/SqoopUserGuide.xml
 
 $(BUILD_DIR)/SqoopDevGuide.html: dev/*.txt
-	asciidoc -a toc -a toclevels=1 -a "toc-title=Table of Contents" \
-		-a revnumber=$(VERSION) -a "revdate=$(REVDATE)" \
-		dev/SqoopDevGuide.txt
 	mkdir -p $(BUILD_DIR)
-	mv dev/SqoopDevGuide.html $(BUILD_DIR)
+	asciidoc --unsafe -a revnumber=$(VERSION) \
+		-b docbook \
+		dev/SqoopDevGuide.txt
+	xmlto -o $(BUILD_DIR) -m web/html.xsl html-nochunks dev/SqoopDevGuide.xml
+	rm dev/SqoopDevGuide.xml
+
+$(BUILD_DIR)/index.html: web/index.txt
+	mkdir -p $(BUILD_DIR)
+	asciidoc --unsafe -a revnumber=$(VERSION) \
+	  -b docbook \
+		web/index.txt
+	xmlto -o $(BUILD_DIR) -m web/html.xsl html-nochunks web/index.xml
+	rm web/index.xml
+
+supportfiles:
+	mkdir -p $(BUILD_DIR)
+	cp web/docbook.css $(BUILD_DIR)
+	rsync -a web/images $(BUILD_DIR)/
 
 clean:
 	-rm $(BUILD_DIR)/sqoop-*.1.gz
@@ -81,5 +94,5 @@ clean:
 	-rm user/SqoopUserGuide.html
 	-rm dev/SqoopDevGuide.html
 
-.PHONY: all man userguide devguide clean
+.PHONY: all man userguide devguide clean supportfiles index
 
diff --git a/src/docs/web/index.txt b/src/docs/web/index.txt
index aeb8f3fa..37980a5d 100644
--- a/src/docs/web/index.txt
+++ b/src/docs/web/index.txt
@@ -25,4 +25,6 @@ The following pages are the documentation for Sqoop v{revnumber}:
 
 - link:SqoopUserGuide.html[Sqoop User Guide]
 - link:SqoopDevGuide.html[Sqoop Developer's Guide]
+- link:sqoop-{revnumber}.releasenotes.html[Release Notes]
+- link:api/index.html[API Documentation]