SOLR-3733: First version of patch (without Robert's changes)

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/branches/solr3733@1388082 13f79535-47bb-0310-9956-ffa450edef68

build.xml

@@ -25,7 +25,7 @@
   </target>
 
   <target name="precommit" description="Run basic checks before committing"
-          depends="check-svn-working-copy,validate,javadocs-lint"/>
+          depends="check-svn-working-copy,validate,documentation-lint"/>
 
   <target name="test" description="Test both Lucene and Solr">
     <sequential>
@@ -47,16 +47,16 @@
 
   <target name="javadocs" description="Generate Lucene and Solr javadocs">
     <sequential>
-      <subant target="javadocs" inheritall="false" failonerror="true">
+      <subant target="documentation" inheritall="false" failonerror="true">
         <fileset dir="lucene" includes="build.xml" />
         <fileset dir="solr" includes="build.xml" />
       </subant>
     </sequential>
   </target>
 
-  <target name="javadocs-lint">
+  <target name="documentation-lint">
     <sequential>
-      <subant target="javadocs-lint" inheritall="false" failonerror="true">
+      <subant target="documentation-lint" inheritall="false" failonerror="true">
         <fileset dir="lucene" includes="build.xml" />
         <fileset dir="solr" includes="build.xml" />
       </subant>
@@ -305,7 +305,7 @@
   </target>
 
   <!-- Jenkins tasks -->
-  <target name="jenkins-hourly" depends="clean,test,validate,-jenkins-javadocs-lint,jar-checksums,check-svn-working-copy" description="Runs the Jenkins hourly test runs"/>
+  <target name="jenkins-hourly" depends="clean,test,validate,-jenkins-documentation-lint,jar-checksums,check-svn-working-copy" description="Runs the Jenkins hourly test runs"/>
   
   <target name="jenkins-clover" description="Runs nightly clover builds on Jenkins">
     <antcall target="-jenkins-clover">
@@ -325,11 +325,11 @@
     description="Runs the nightly Maven build on Jenkins, including artifact deployment"/>
   
   <!-- we need this extra condition, as we want to match only on "true", not solely if property is set: -->
-  <property name="disable.javadocs-lint" value="false" />
-  <condition property="-disable.javadocs-lint">
-    <istrue value="${disable.javadocs-lint}"/>
+  <property name="disable.documentation-lint" value="false" />
+  <condition property="-disable.documentation-lint">
+    <istrue value="${disable.documentation-lint}"/>
   </condition>
-  <target name="-jenkins-javadocs-lint" unless="-disable.javadocs-lint">
-    <antcall target="javadocs-lint"/> 
+  <target name="-jenkins-documentation-lint" unless="-disable.documentation-lint">
+    <antcall target="documentation-lint"/> 
   </target>
 </project>

lucene/build.xml

@@ -225,7 +225,7 @@
   <target name="javadocs" description="Generate javadoc" depends="javadocs-lucene-core, javadocs-modules, javadocs-test-framework"/>
 
   <!-- we check for broken links across all documentation -->
-  <target name="javadocs-lint" depends="documentation">
+  <target name="documentation-lint" depends="documentation">
     <sequential>
       <check-broken-links dir="build/docs"/>
       <!-- TODO: change this level=class -->

solr/build.xml

@@ -26,7 +26,7 @@
     <echo message="Use 'ant clean' to clean compiled files." />
     <echo message="Use 'ant compile' to compile the source code." />
     <echo message="Use 'ant dist' to build the project WAR and JAR files." />
-    <echo message="Use 'ant javadocs' to build javadocs under build/docs/api" />
+    <echo message="Use 'ant documentation' to build documentation." />
     <echo message="Use 'ant generate-maven-artifacts' to generate maven artifacts." />
     <echo message="Use 'ant package' to generate zip, tgz for distribution." />
     <!--<echo message="Use 'ant luke' to start luke.  see: http://luke.googlecode.com" />-->
@@ -138,15 +138,50 @@
   <target name="compile-test" description="Compile unit tests."
           depends="compile-solr-test-framework, compile-test-solr-core, compile-test-solrj, compile-test-contrib"/>
   <target name="javadocs" description="Calls javadocs-all, javadocs-solrj, and javadocs-test-framework"
-          depends="javadocs-all,javadocs-solrj,javadocs-test-framework"/>
+          depends="javadocs-solr-core,javadocs-solrj,javadocs-test-framework,javadocs-contrib"/>
+  <target name="documentation" description="Generate all documentation"
+    depends="javadocs,changes-to-html,process-webpages"/>
   <target name="compile-core" depends="compile-solr-core" unless="solr.core.compiled"/>
   
+  <target name="process-webpages" depends="resolve-pegdown">
+    <makeurl property="process-webpages.buildfiles" separator="|">
+      <fileset dir="." includes="core/build.xml,test-framework/build.xml,solrj/build.xml,contrib/**/build.xml"/>
+    </makeurl>
+    <!--
+      The XSL input file is ignored completely, but XSL expects one to be given,
+      so we pass ourself (${ant.file}) here. The list of module build.xmls is given
+      via string parameter, that must be splitted by the XSL at '|'.
+    --> 
+    <xslt in="${ant.file}" out="${javadoc.dir}/index.html" style="site/xsl/index.xsl" force="true">
+      <outputproperty name="method" value="html"/>
+      <outputproperty name="version" value="4.0"/>
+      <outputproperty name="encoding" value="UTF-8"/>
+      <outputproperty name="indent" value="yes"/>
+      <param name="buildfiles" expression="${process-webpages.buildfiles}"/>
+      <param name="version" expression="${version}"/>
+    </xslt>
+    
+    <pegdown todir="${javadoc.dir}">
+      <fileset dir="." includes="MIGRATE.txt,JRE_VERSION_MIGRATION.txt"/>
+      <globmapper from="*.txt" to="*.html"/>
+    </pegdown>
+
+    <copy todir="${javadoc.dir}">
+      <fileset dir="site/html" includes="**/*"/>
+    </copy>
+  </target>
+
   <!-- Solr core targets -->
   <target name="test-solr-core" description="Test solr core">
     <ant dir="core" target="test" inheritAll="false">
       <propertyset refid="uptodate.and.compiled.properties"/>
     </ant>
   </target>
+  <target name="javadocs-solr-core">
+    <ant dir="core" target="javadocs" inheritAll="false">
+      <propertyset refid="uptodate.and.compiled.properties"/>
+    </ant>
+  </target>
   
   <!-- Solrj targets -->
   <target name="test-solrj" description="Test java client">
@@ -430,7 +465,7 @@
                             dist/solrj-lib/*
                             dist/test-framework/**"
                   excludes="**/*.tgz **/*.zip **/*.md5 **/*src*.jar **/*docs*.jar **/*.sha1" />
-      <tarfileset dir="${dest}/docs"
+      <tarfileset dir="${javadoc.dir}"
                   prefix="${fullnamever}/docs" />
     </tar>
     <make-checksums file="${package.dir}/${fullnamever}.tgz"/>
@@ -496,66 +531,12 @@
     </sequential>
   </target>
 
-  <!-- since we build across all contribs, we must ensure all deps
-       are resolved -->
-  <target name="javadocs-all"
-          depends="resolve,prep-lucene-jars,javadocs-dep,lucene-javadocs,define-lucene-javadoc-url"
-          description="Generate javadoc for core, java client and contrib">
-    <sequential>
-      <mkdir dir="${dest}/docs/api"/>
- 
-      <!-- TODO: optimize this, thats stupid here: -->
-      <subant target="module-jars-to-solr">
-        <fileset dir="contrib/analysis-extras" includes="build.xml"/>
-      </subant>
-
-      <!-- TODO: optimize this, thats stupid here: -->
-      <subant target="module-jars-to-solr">
-        <fileset dir="contrib/uima" includes="build.xml"/>
-      </subant>
-
-      <path id="javadoc.classpath">
-        <path refid="test.classpath"/>
-        <fileset dir="${dest}/contrib">
-          <include name="**/lucene-libs/**/*.jar"/>
-        </fileset>
-        <fileset dir="contrib">
-          <include name="**/lib/**/*.jar"/>
-          <exclude name="**/analysis-extras/lib/**/*icu4j*.jar"/> <!-- extraction/lib/ has this one -->
-        </fileset>
-        <pathelement location="${dest}/solr-solrj/classes/java"/>
-      </path>
- 
-      <solr-invoke-javadoc destdir="${dest}/docs/api"
-                      overview="core/src/java/overview.html">
-        <solrsources>
-          <packageset dir="core/src/java" />
-          <packageset dir="solrj/src/java" />
-          <packageset dir="contrib/analysis-extras/src/java"/>
-          <packageset dir="contrib/clustering/src/java"/>
-          <packageset dir="contrib/dataimporthandler/src/java"/>
-          <packageset dir="contrib/dataimporthandler-extras/src/java"/>
-          <packageset dir="contrib/extraction/src/java"/>
-          <packageset dir="contrib/langid/src/java"/>
-          <packageset dir="contrib/uima/src/java"/>
-          <group title="Core" packages="org.apache.*" />
-          <group title="SolrJ" packages="org.apache.solr.common.*,org.apache.solr.client.solrj.*,org.apache.zookeeper.*" />
-          <group title="contrib: Clustering" packages="org.apache.solr.handler.clustering*" />
-          <group title="contrib: DataImportHandler" packages="org.apache.solr.handler.dataimport*" />
-          <group title="contrib: Solr Cell" packages="org.apache.solr.handler.extraction*" />
-          <group title="contrib: Solr LangId" packages="org.apache.solr.update.processor.LanguageIdentifier*,org.apache.solr.update.processor.LangIdParams*,org.apache.solr.update.processor.DetectedLanguage*" />
-          <group title="contrib: Solr UIMA" packages="org.apache.solr.uima*" />
-        </solrsources>
-      </solr-invoke-javadoc>
-    </sequential>
-  </target>
-
   <!-- TODO: does solr have any other docs we should check? -->
   <!-- TODO: also integrate checkJavaDocs.py, which does more checks -->
-  <target name="javadocs-lint" depends="javadocs">
-    <check-broken-links dir="build/docs"/>
+  <target name="documentation-lint" depends="documentation">
+    <check-broken-links dir="${javadoc.dir}"/>
     <!-- TODO: add missing package.htmls and bump this to level=package -->
-    <check-missing-javadocs dir="build/docs" level="none"/>
+    <check-missing-javadocs dir="${javadoc.dir}" level="none"/>
   </target>
  
   <!-- install-maven-tasks is *not* a useless dependency. do not remove -->

solr/common-build.xml

@@ -37,16 +37,16 @@
   <property name="javac.target" value="1.6"/>
   <property name="javac.args" value=""/>
   
-  <property name="dest" value="${common-solr.dir}/build" />
+  <property name="dest" location="${common-solr.dir}/build" />
   <property name="build.dir" location="${dest}/${ant.project.name}"/>
   <property name="dist" location="${common-solr.dir}/dist"/>
   <property name="package.dir" location="${common-solr.dir}/package"/>
   <property name="maven.dist.dir" location="${package.dir}/maven"/>
   <property name="lucene-libs" location="${dest}/lucene-libs" />
-  <property name="tests.userdir" value="src/test-files"/>
-  <property name="example" value="${common-solr.dir}/example" />
-  <property name="javadoc.dir" location="${build.dir}/docs/api"/>
-  <property name="tests.loggingfile" value="${common-solr.dir}/testlogging.properties"/>
+  <property name="tests.userdir" location="src/test-files"/>
+  <property name="example" location="${common-solr.dir}/example" />
+  <property name="javadoc.dir" location="${dest}/docs"/>
+  <property name="tests.loggingfile" location="${common-solr.dir}/testlogging.properties"/>
   <property name="tests.cleanthreads.sysprop" value="perClass"/>
 
   <property name="changes.target.dir" value="${dest}/docs/changes"/>
@@ -202,20 +202,20 @@
   <!-- create javadocs for the current module -->
   <target name="javadocs" depends="compile-core,define-lucene-javadoc-url,lucene-javadocs">
    	<sequential>
-      <mkdir dir="${javadoc.dir}"/>
+      <mkdir dir="${javadoc.dir}/${name}"/>
       <solr-invoke-javadoc>
         <solrsources>
           <packageset dir="${src.dir}"/>
         </solrsources>
       </solr-invoke-javadoc>
-      <solr-jarify basedir="${javadoc.dir}" destfile="${build.dir}/${final.name}-javadoc.jar"/>
+      <solr-jarify basedir="${javadoc.dir}/${name}" destfile="${build.dir}/${final.name}-javadoc.jar"/>
      </sequential>
   </target>
 
   <!-- macro to create solr javadocs with links to lucene. make sure calling task depends on lucene-javadocs -->
   <macrodef name="solr-invoke-javadoc">
       <element name="solrsources" optional="yes"/>
-      <attribute name="destdir" default="${javadoc.dir}"/>
+      <attribute name="destdir" default="${javadoc.dir}/${name}"/>
       <attribute name="title" default="${Name} ${version} ${name} API"/>
       <attribute name="overview" default="${src.dir}/overview.html"/>
     <sequential>
@@ -393,10 +393,15 @@
   <target name="compile-contrib" description="Compile contrib modules">
   	<contrib-crawl target="compile-core"/>
   </target>
+  
   <target name="compile-test-contrib" description="Compile contrib modules' tests">
   	<contrib-crawl target="compile-test"/>
   </target>
 
+  <target name="javadocs-contrib" description="Compile contrib modules">
+  	<contrib-crawl target="javadocs"/>
+  </target>
+
   <target name="contribs-add-to-war">
     <mkdir dir="${dest}/web"/>
     <delete dir="${dest}/web" includes="**/*" failonerror="false"/>

solr/core/src/java/overview.html

@@ -16,6 +16,6 @@
 -->
 <html>
 <body>
-Apache Solr Search Server, new users should familiarize themselves with the <a href="doc-files/tutorial.html">Solr Tutorial</a>.
+Apache Solr Search Server (Core Javadocs).
 </body>
 </html>

solr/site/xsl/index.xsl

@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<xsl:stylesheet version="1.0" 
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:str="http://exslt.org/strings"
+  extension-element-prefixes="str"
+>
+  <xsl:param name="buildfiles"/>
+  <xsl:param name="version"/>
+  
+  <!--
+    NOTE: This template matches the root element of any given input XML document!
+    The XSL input file is ignored completely, but XSL expects one to be given,
+    so build.xml passes itself here. The list of module build.xmls is given via
+    string parameter, that must be splitted at '|'.
+  --> 
+  <xsl:template match="/">
+    <html>
+      <head>
+        <title><xsl:text>Apache Solr </xsl:text><xsl:value-of select="$version"/><xsl:text> Documentation</xsl:text></title>
+      </head>
+      <body>
+        <div><img src="solr.png"/></div>
+        <h1><xsl:text>Apache Solr </xsl:text><xsl:value-of select="$version"/><xsl:text> Documentation</xsl:text></h1>
+        <p>Solr is the popular, blazing fast open source enterprise search platform from the Apache Lucene project.
+        Its major features include powerful full-text search, hit highlighting, faceted search, dynamic clustering,
+        database integration, rich document (e.g., Word, PDF) handling, and geospatial search. Solr is highly scalable,
+        providing distributed search and index replication, and it powers the search and navigation features of many
+        of the world's largest internet sites.</p>
+        <p>Solr is written in Java and runs as a standalone full-text search server within a servlet container such as
+        Jetty. Solr uses the Lucene Java search library at its core for full-text indexing and search, and has REST-like
+        HTTP/XML and JSON APIs that make it easy to use from virtually any programming language. Solr's powerful external
+        configuration allows it to be tailored to almost any type of application without Java coding, and it has an extensive
+        plugin architecture when more advanced customization is required.</p>
+        <p>
+          This is the official documentation for <b><xsl:text>Apache Solr </xsl:text>
+          <xsl:value-of select="$version"/></b>. Additional documentation is available in the
+          <a href="http://wiki.apache.org/solr">Wiki</a>.
+        </p>
+        <h2>Reference Documents</h2>
+          <ul>
+            <li><a href="changes/Changes.html">Changes</a>: List of changes in this release.</li>
+            <li><a href="tutorial.html">Solr Tutorial</a>: This document covers the basics of running Solr using an example schema, and some sample data.</li>
+          </ul>
+        <h2>API Javadocs</h2>
+        <xsl:call-template name="modules"/>
+      </body>
+    </html>
+	</xsl:template>
+	
+  <xsl:template name="modules">
+    <ul>
+      <xsl:for-each select="str:split($buildfiles,'|')">
+        <!-- hack to list "core" and "solrj" first, contains() returns "true" which sorts before "false" if descending: -->
+        <xsl:sort select="string(contains(text(), '/core/'))" order="descending" lang="en"/>
+        <xsl:sort select="string(contains(text(), '/solrj/'))" order="descending" lang="en"/>
+        <!-- hack to list "test-framework" at the end, contains() returns "true" which sorts after "false" if ascending: -->
+        <xsl:sort select="string(contains(text(), '/test-framework/'))" order="ascending" lang="en"/>
+        <!-- sort the remaining build files by path name: -->
+        <xsl:sort select="text()" order="ascending" lang="en"/>
+        
+        <xsl:variable name="buildxml" select="document(.)"/>
+        <xsl:variable name="name" select="$buildxml/*/@name"/>
+        <li>
+          <xsl:if test="$name='solr-core'">
+            <xsl:attribute name="style">font-size:larger; margin-bottom:.5em;</xsl:attribute>
+          </xsl:if>
+          <b><a href="{$name}/index.html"><xsl:value-of select="$name"/>
+          </a><xsl:text>: </xsl:text></b>
+          <xsl:value-of select="normalize-space($buildxml/*/description)"/>
+        </li>
+      </xsl:for-each>
+    </ul>
+  </xsl:template>
+
+</xsl:stylesheet>

solr/solrj/build.xml

@@ -42,12 +42,5 @@
     </copy>
   </target>
 
-  <target name="javadocs" depends="common-solr.javadocs">
-    <mkdir dir="${dest}/docs/api/solrj"/>
-    <copy todir="${dest}/docs/api/solrj">
-      <fileset dir="${javadoc.dir}"/>
-    </copy>
-  </target>
-
   <target name="dist-maven" depends="dist-maven-src-java"/>
 </project>

solr/test-framework/build.xml

@@ -48,7 +48,7 @@
   <target name="javadocs"
           depends="compile-core,jar-test-framework,lucene-javadocs,javadocs-test-framework,define-lucene-javadoc-url">
     <sequential>
-      <mkdir dir="${javadoc.dir}"/>
+      <mkdir dir="${javadoc.dir}/${name}"/>
       <!-- NOTE: explicitly not using solr-invoke-javadoc, or attempting to 
 	   link to lucene-test-framework because if we did javadoc would 
 	   attempt to link class refs in in org.apache.lucene, causing 
@@ -56,7 +56,7 @@
 	   lucene-test-framework was first, or broken links to things like 
 	   LuceneTestCase if lucene-core was first)
       -->
-      <invoke-javadoc destdir="${javadoc.dir}" 
+      <invoke-javadoc destdir="${javadoc.dir}/${name}" 
 		      title="${Name} ${version} Test Framework API">
 	<sources>
 	  <link offline="true" href="${javadoc.link.junit}"
@@ -64,11 +64,7 @@
 	  <packageset dir="${src.dir}"/>
 	</sources>
       </invoke-javadoc>
-      <solr-jarify basedir="${javadoc.dir}" destfile="${build.dir}/${final.name}-javadoc.jar"/>
-      <mkdir dir="${dest}/docs/api/test-framework"/>
-      <copy todir="${dest}/docs/api/test-framework">
-        <fileset dir="${javadoc.dir}"/>
-      </copy>
+      <solr-jarify basedir="${javadoc.dir}/${name}" destfile="${build.dir}/${final.name}-javadoc.jar"/>
     </sequential>
   </target>