SAMZA-259: Restructure documentation folders

bin/generate-javadocs.sh

@@ -18,17 +18,7 @@
 
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 BASE_DIR=$DIR/..
-VERSION=$1
-JAVADOC_DIR=$BASE_DIR/docs/learn/documentation/$VERSION/api/javadocs
-
-if test -z "$VERSION"; then
-  echo
-  echo "  USAGE:"
-  echo
-  echo "    ${BASH_SOURCE[0]##*/} 0.7.0"
-  echo
-  exit 0
-fi
+JAVADOC_DIR=$BASE_DIR/docs/learn/documentation/versioned/api/javadocs
 
 cd $BASE_DIR
 ./gradlew javadoc

bin/publish-site.sh

@@ -19,29 +19,30 @@
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 BASE_DIR=$DIR/..
 DOCS_DIR=$BASE_DIR/docs
-VERSION=$1
-COMMENT=$2
-USER=$3
+COMMENT=$1
+USER=$2
 
-if test -z "$VERSION" || test -z "$COMMENT" || test -z "$USER"; then
+if test -z "$COMMENT" || test -z "$USER"; then
   echo
   echo "  USAGE:"
   echo
-  echo "    ${BASH_SOURCE[0]##*/} 0.7.0 \"updating welcome page\" criccomini"
+  echo "    ${BASH_SOURCE[0]##*/} \"updating welcome page\" criccomini"
   echo
   exit 0
 fi
 
 echo "Using uer: $USER"
-echo "Using version: $VERSION"
 echo "Using comment: $COMMENT"
 echo "Generating javadocs."
-$BASE_DIR/bin/generate-javadocs.sh $VERSION
+$BASE_DIR/bin/generate-javadocs.sh
 
 echo "Building site."
 cd $DOCS_DIR
 bundle exec jekyll build
 
+echo "Replacing version"
+./_docs/replace-versioned.sh
+
 echo "Checking out SVN site."
 SVN_TMP=`mktemp -d /tmp/samza-svn.XXXX`
 svn co https://svn.apache.org/repos/asf/incubator/samza/ $SVN_TMP

docs/README.md

@@ -30,19 +30,27 @@ To compile the website in the \_site directory, execute:
 
     bundle exec jekyll build
 
+To test the site,
+
+    * run:
+
+      bundle exec jekyll serve --watch --baseurl
+
+    * then open another command line window and run:
+
+      _docs/local-site-test.sh
+
 ## Versioning
 
-The "Learn" section of this website is versioned. To add a new version, copy the folder at the version number-level (0.7.0 to 0.8.0, for example).
+The "learn" and "img" sections are versioned. To add a new version, change the version number in _config.yml. All links in pages should use
 
-All links between pages inside a versioned folder should be relative links, not absolute.
+{{site.version}}, not hard-coded version number.
 
 ## Javadocs
 
 To auto-generate the latest Javadocs, run:
 
-    bin/generate-javadocs.sh <version>
-
-The version number is the number that will be used in the /docs/learn/documentation/<version>/api/javadocs path.
+    bin/generate-javadocs.sh
 
 ## Release
 

docs/_config.yml

@@ -21,3 +21,8 @@ markdown: redcarpet
 exclude: ['_notes']
 redcarpet:
   extensions: ['with_toc_data', 'smart']
+exclude: [_docs]
+baseurl: http://samza.incubator.apache.org
+version: latest
+# this is the version you will go if you click 'switch version' in "latest" pages.
+latest-release: 0.7.0

docs/_docs/local-site-test.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# 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.
+
+# The goal of this script is to make testing the site locally easier.
+# It downloads old pages from SVN and replaces with/add new pages.
+
+DIR=$(dirname $0)/..
+cd $DIR
+
+echo "downloading SVN..."
+SVN_TMP=`mktemp -d /tmp/samza-svn.XXXX`
+svn co https://svn.apache.org/repos/asf/incubator/samza/ $SVN_TMP
+cp -r _site/* $SVN_TMP/site/
+cp -r $SVN_TMP/site/* _site
+rm -rf $SVN_TMP
+
+# replace version number
+echo "replacing version number..."
+_docs/replace-versioned.sh

docs/_docs/replace-versioned.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# 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.
+
+# get the version number
+version=`cat _config.yml | grep 'version:' | cut -d' ' -f 2`
+latestRelease=`cat _config.yml | grep 'latest-release:' | cut -d' ' -f 2`
+DIR=$(dirname $0)/..
+
+if test -z "$version" || test -z "$latestRelease"; then
+  echo "Please make sure _config.yml has \"version\" and \"latest-release\""
+  exit 0
+fi
+
+echo "version:" $version
+
+echo "replaced img/versioned to img/"$version
+mv -f $DIR/_site/img/versioned $DIR/_site/img/$version
+
+echo "replaced learn/documentation/versioned to learn/documentation/"$version
+mv -f $DIR/_site/learn/documentation/versioned $DIR/_site/learn/documentation/$version
+
+echo "replaced learn/tutorials/versioned to learn/tutorials/"$version
+mv -f $DIR/_site/learn/tutorials/versioned $DIR/_site/learn/tutorials/$version
+
+echo "replaced startup/hello-samza/versioned to startup/hello-samza/"$version
+mv -f $DIR/_site/startup/hello-samza/versioned $DIR/_site/startup/hello-samza/$version

docs/_layouts/default.html

@@ -40,6 +40,9 @@
                 <a href="/startup/download"><i class="fa fa-arrow-circle-o-down masthead-icon"></i></a>
                 <a href="https://git-wip-us.apache.org/repos/asf?p=incubator-samza.git;a=tree" target="_blank"><i class="fa fa-code masthead-icon" style="font-weight: bold;"></i></a>
                 <a href="https://twitter.com/samzastream" target="_blank"><i class="fa fa-twitter masthead-icon"></i></a>
+                {% if page.url contains "versioned" %}
+                  <a href="{{site.baseurl}}/{% if site.version == "latest" %}{{page.url | replace:'versioned', site.latest-release | replace_first: '/', ''}}{% else %}{{page.url | replace:'versioned', 'latest' | replace_first: '/', ''}}{% endif %}"><i class="fa fa-history masthead-icon"></i></a>
+                {% endif %}
               </div>
             </div>
           </div><!-- /.container -->
@@ -49,14 +52,14 @@
           <div class="menu">
             <h1><i class="fa fa-rocket"></i> Getting Started</h1>
             <ul>
-              <li><a href="/startup/hello-samza/0.7.0">Hello Samza</a></li>
+              <li><a href="/startup/hello-samza/latest">Hello Samza</a></li>
               <li><a href="/startup/download">Download</a></li>
             </ul>
 
             <h1><i class="fa fa-book"></i> Learn</h1>
             <ul>
-              <li><a href="/learn/documentation/0.7.0">Documentation</a></li>
-              <li><a href="/learn/tutorials/0.7.0">Tutorials</a></li>
+              <li><a href="/learn/documentation/latest">Documentation</a></li>
+              <li><a href="/learn/tutorials/latest">Tutorials</a></li>
               <li><a href="http://wiki.apache.org/samza/FAQ">FAQ</a></li>
               <li><a href="http://wiki.apache.org/samza">Wiki</a></li>
               <li><a href="http://wiki.apache.org/samza/PapersAndTalks">Papers &amp; Talks</a></li>
@@ -84,6 +87,11 @@ <h1><i class="fa fa-code"></i> Contribute</h1>
               <li><a href="https://builds.apache.org/">Unit Tests</a></li>
               <li><a href="/contribute/disclaimer.html">Disclaimer</a></li>
             </ul>
+
+            <h1><i class="fa fa-history"></i> Archive</h1>
+            <ul>
+              <li><a href="/archive/index.html">0.7.0</a></li>
+            </ul>
           </div>
 
           <div class="content">

docs/archive/index.html

@@ -0,0 +1,28 @@
+---
+layout: page
+title: Documentation
+---
+<!--
+   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.
+-->
+
+<h4>0.7.0 Release</h4>
+
+<ul class="documentation-list">
+  <li><a href="../learn/documentation/0.7.0">Documentation</a></li>
+  <li><a href="../learn/tutorials/0.7.0">Tutorials</a></li>
+  <li><a href="../startup/hello-samza/0.7.0">Hello Samza</a></li>
+</ul>